[
https://issues.apache.org/jira/browse/JCR-5170?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Karol Lewandowski updated JCR-5170:
-----------------------------------
Description:
Hello. I'm working on the support for CND files in an IntelliJ Platform plugin
(aemide.com).
I noticed the node types documentation notation and would like to propose
improvements in the documentation convention.
Currently, docs are created for node types only (or mostly). They include doc
tags for properties ({{{}@prop{}}}) and child nodes (@node).
{code:java}
<ex = 'http://www.example.com/jcr/ex/1.0'>
/**
* Defines the configuration for something.
*
* @prop ex:align alignment of something:
* use 'right' for rendering on the right,
* use 'left' for rendering on the left,
* use 'auto' for automatic rendering
* @node ex:child an example child config
* @prop ex:enabled if true, something will be enabled somewhere
*/
[ex:ExConfig] > nt:unstructured, nt:hierarchyNode
orderable
- ex:enabled (boolean)
/**
* @since 1.0 <--- doc split into two places!!!
*/
- ex:align (string) < 'right', 'left', 'auto'
+ ex:child (ex:ExChildConfig) = ex:ExChildConfig
{code}
There are problems with this approach:
# Node type docs are very long, making it harder to read them.
# Properties and children docs are not bound to the properties and child nodes
declarations, making it harder to read a property's or node's doc. Often,
{{@prop}} and {{@node}} tags are ordered differently from actual property and
child node definitions.
# Sometimes, a doc for a property or child is split between the node type's
doc and property/child doc (see example below).
# The notation is not intuitive. If we relate to a object oriented programming
language, node types are like classes and properties and child nodes are like
members. In most OOP language, members are documented directly before their
declarations. Imagine Javadocs documentated all class fields and methods in the
class' doc.
# It's hard to parse and clearly display information about properties with
restricted values, as they are plain text.
For example, {{ex:align}} is rendered as:
!Screenshot 2025-07-15 at 16.53.07.png|width=442,height=347!
Am I missing something important in this convention?
h2. The Proposal
The proposal is to document properties and children directly before
declarations:
{code:java}
<ex = 'http://www.example.com/jcr/ex/1.0'>
/**
* Defines the configuration for something.
*/
[ex:ExConfig] > nt:unstructured, nt:hierarchyNode
orderable
/**
* If true, something will be enabled somewhere.
*/
- ex:enabled (boolean)
/**
* Alignment of something
*
* @value right for rendering on the right
* @value left for rendering on the left
* @value auto for automatic rendering
* @since 1.0 <--- everything is in one place
*/
- ex:align (string) < 'right', 'left', 'auto'
/**
* An example child config.
*/
+ ex:child (ex:ExChildConfig) = ex:ExChildConfig
{code}
The CND parser allows using this approach.
It makes docs clear and well-organized. Tooling can parse and display
information about each element more easily and produce much better renditions,
for example:
!Screenshot 2025-07-15 at 16.52.12.png|width=450,height=389!
What do you think?
If you agree, I can improve the existing docs to follow this approach (I mean
CND for built-in node types and external, if allowed).
was:
Hello. I'm working on the support for CND files in an IntelliJ Platform plugin
(aemide.com).
I noticed the node types documentation notation and would like to propose
improvements in the documentation convention.
Currently, docs are created for node types only (or mostly). They include doc
tags for properties ({{{}@prop{}}}) and child nodes (@node).
{code:java}
<ex = 'http://www.example.com/jcr/ex/1.0'>
/**
* Defines the configuration for something.
*
* @prop ex:align alignment of something:
* use 'right' for rendering on the right,
* use 'left' for rendering on the left,
* use 'auto' for automatic rendering
* @node ex:child an example child config
* @prop ex:enabled if true, something will be enabled somewhere
*/
[ex:ExConfig] > nt:unstructured, nt:hierarchyNode
orderable
- ex:enabled (boolean)
/**
* @since 1.0 <--- doc split into two places!!!
*/
- ex:align (string) < 'right', 'left', 'auto'
+ ex:child (ex:ExChildConfig) = ex:ExChildConfig
{code}
There are problems with this approach:
# Node type docs are very long, making it harder to read them.
# Properties and children docs are not bound to the properties and child nodes
declarations, making it harder to read a property's or node's doc. Often,
{{@prop}} and {{@node}} tags are ordered differently from actual property and
child node definitions.
# Sometimes, a doc for a property or child is split between the node type's
doc and property/child doc (see example below).
# The notation is not intuitive. If we relate to a object oriented programming
language, node types are like classes and properties and child nodes are like
members. In most OOP language, members are documented directly before their
declarations. Imagine Javadocs documentated all class fields and methods in the
class' doc.
# It's hard to parse and clearly display information about properties with
restricted values, as they are plain text.
For example, {{ex:align}} is rendered as:
!Screenshot 2025-07-15 at 16.53.07.png|width=442,height=347!
Am I missing something important in this convention?
h2. The Proposal
The proposal is to document properties and children directly before
declarations:
{code:java}
<ex = 'http://www.example.com/jcr/ex/1.0'>
/**
* Defines the configuration for something.
*/
[ex:ExConfig] > nt:unstructured, nt:hierarchyNode
orderable
/**
* If true, something will be enabled somewhere.
*/
- ex:enabled (boolean)
/**
* Alignment of something
*
* @value right for rendering on the right
* @value left for rendering on the left
* @value auto for automatic rendering
* @since 1.0 <--- everything is in one place
*/
- ex:align (string) < 'right', 'left', 'auto'
/**
* An example child config.
*/
+ ex:child (ex:ExChildConfig) = ex:ExChildConfig
{code}
The CND parser allows using this approach.
It makes docs clear and well-organized. Tooling can parse and display
information about each element more easily and produce much better renditions,
for example:
!Screenshot 2025-07-15 at 16.52.12.png|width=450,height=389!
What do you think?
If you agree, I can improve the existing docs to follow this approach (I mean
CND for built-in node types and external, if allowed).
> Proposal for improving the CND docs convention
> ----------------------------------------------
>
> Key: JCR-5170
> URL: https://issues.apache.org/jira/browse/JCR-5170
> Project: Jackrabbit Content Repository
> Issue Type: Improvement
> Reporter: Karol Lewandowski
> Priority: Minor
> Labels: cnd, doc
> Attachments: Screenshot 2025-07-15 at 16.52.12.png, Screenshot
> 2025-07-15 at 16.53.07.png
>
>
> Hello. I'm working on the support for CND files in an IntelliJ Platform
> plugin (aemide.com).
> I noticed the node types documentation notation and would like to propose
> improvements in the documentation convention.
> Currently, docs are created for node types only (or mostly). They include doc
> tags for properties ({{{}@prop{}}}) and child nodes (@node).
>
> {code:java}
> <ex = 'http://www.example.com/jcr/ex/1.0'>
> /**
> * Defines the configuration for something.
> *
> * @prop ex:align alignment of something:
> * use 'right' for rendering on the right,
> * use 'left' for rendering on the left,
> * use 'auto' for automatic rendering
> * @node ex:child an example child config
> * @prop ex:enabled if true, something will be enabled somewhere
> */
> [ex:ExConfig] > nt:unstructured, nt:hierarchyNode
> orderable
> - ex:enabled (boolean)
> /**
> * @since 1.0 <--- doc split into two places!!!
> */
> - ex:align (string) < 'right', 'left', 'auto'
> + ex:child (ex:ExChildConfig) = ex:ExChildConfig
> {code}
>
> There are problems with this approach:
> # Node type docs are very long, making it harder to read them.
> # Properties and children docs are not bound to the properties and child
> nodes declarations, making it harder to read a property's or node's doc.
> Often, {{@prop}} and {{@node}} tags are ordered differently from actual
> property and child node definitions.
> # Sometimes, a doc for a property or child is split between the node type's
> doc and property/child doc (see example below).
> # The notation is not intuitive. If we relate to a object oriented
> programming language, node types are like classes and properties and child
> nodes are like members. In most OOP language, members are documented directly
> before their declarations. Imagine Javadocs documentated all class fields and
> methods in the class' doc.
> # It's hard to parse and clearly display information about properties with
> restricted values, as they are plain text.
> For example, {{ex:align}} is rendered as:
> !Screenshot 2025-07-15 at 16.53.07.png|width=442,height=347!
> Am I missing something important in this convention?
> h2. The Proposal
> The proposal is to document properties and children directly before
> declarations:
>
> {code:java}
> <ex = 'http://www.example.com/jcr/ex/1.0'>
> /**
> * Defines the configuration for something.
> */
> [ex:ExConfig] > nt:unstructured, nt:hierarchyNode
> orderable
> /**
> * If true, something will be enabled somewhere.
> */
> - ex:enabled (boolean)
> /**
> * Alignment of something
> *
> * @value right for rendering on the right
> * @value left for rendering on the left
> * @value auto for automatic rendering
> * @since 1.0 <--- everything is in one place
> */
> - ex:align (string) < 'right', 'left', 'auto'
> /**
> * An example child config.
> */
> + ex:child (ex:ExChildConfig) = ex:ExChildConfig
> {code}
>
> The CND parser allows using this approach.
> It makes docs clear and well-organized. Tooling can parse and display
> information about each element more easily and produce much better
> renditions, for example:
> !Screenshot 2025-07-15 at 16.52.12.png|width=450,height=389!
> What do you think?
> If you agree, I can improve the existing docs to follow this approach (I mean
> CND for built-in node types and external, if allowed).
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
