[MNG-8489] Clean up model description and API doc #2023
Conversation
| </description> | ||
| <type>String</type> | ||
| </field> | ||
| <field> | ||
| <name>artifactId</name> | ||
| <version>3.0.0+</version> | ||
| <required>true</required> | ||
| <description>The identifier for this artifact that is unique within the group given by the | ||
| <description>Returns a string that defines a collection of versions within the group given by the |
There was a problem hiding this comment.
It sounds weird to define the artifactId as a collection of version. That's not really what is it imho. The groupId:artifact represents an artifact, and several versions of it can be available. But an artifatId is not a collection of version.
There was a problem hiding this comment.
Yes, this is tricky. There might be a better way of putting this. Note that I am not saying here that a groupId:artifactId is a collection of versions but that it defines a collection of versions. Perhaps I could change it to identifies a collection of versions. I could also make a case for delineates a collection of versions, though that word is a little obscure for technical writing.
|
Would be best, later, to backport to 3.x line to have model 4.0.0 updated. |
| @@ -104,9 +104,9 @@ | |||
| <field xdoc.separator="blank"> | |||
| <name>parent</name> | |||
| <version>4.0.0+</version> | |||
| <description>The location of the parent project, if one exists. Values from the parent | |||
| <description>Returns the coordinates of the parent project, if one exists. Values from the parent | |||
There was a problem hiding this comment.
The description fields are not only used to document the getter.
In maven 3, the description is used to generate javadoc for the field, getter and setter:
- https://maven.apache.org/ref/3.9.6/maven-model/xref/org/apache/maven/model/Model.html#L36
- https://maven.apache.org/ref/3.9.6/maven-model/xref/org/apache/maven/model/Model.html#L603
- https://maven.apache.org/ref/3.9.6/maven-model/xref/org/apache/maven/model/Model.html#L954
The modello used to slightly transform the description at generation time to accommodate the field, getter and setter. Maybe we should get back to that behavior instead ? I'd rather keep the model descriptive and not tied to the generator.
There was a problem hiding this comment.
Btw, the javadoc is not generated anymore when generating the Maven 3 model...
There was a problem hiding this comment.
Bleah. If i had my druthers, we wouldn't generate any of this. If we're going to use Modello to generate Javadocs, then we need to get the docs right.
For the field, we can drop it. It's private and doesn't need Javadoc. Do we have setters? We likely shouldn't.
I am surprised to hear that "the javadoc is not generated anymore when generating the Maven 3 model." If so, where did it come from? I noticed this problem when looking at the generated code.
There was a problem hiding this comment.
Bleah. If i had my druthers, we wouldn't generate any of this. If we're going to use Modello to generate Javadocs, then we need to get the docs right.
For the field, we can drop it. It's private and doesn't need Javadoc. Do we have setters? We likely shouldn't.
I am surprised to hear that "the javadoc is not generated anymore when generating the Maven 3 model." If so, where did it come from? I noticed this problem when looking at the generated code.
anymore is the key word here. The Maven 3 model now wraps the Maven 4 one and the generator has changed, loosing javadoc generation in the process.
I don't think that's a big problem though, as if people target Maven 4, they should avoid using these classes anymore, and if they don't, they'd rather use the Maven 3 artifacts which have the javadoc.
Also: