Add Javadoc to constructors parameters for properties that have title/description/$comment

[unkish]

Add Javadoc to constructors parameters which have corresponding documented properties. Properties that are not documented (do not have title or description) won't be added to constructors Javadoc.

Following format will be used:

/**
 * {@param {title. }?{description.}?}?
 */

Closes #1463

[joelittlejohn]

I know I recommended this, but I think with this change we will see a new javadoc warning:

warning: no @param for somearg

For any argument that doesn't have @param.

So we get a warning for no param, and we get a warning for param without description. So we're a bit stuck if we don't have a description :thinking: Making up some junk (like "The somearg value") seems pointless too.

[unkish]

I've been thinking about it and couldn't come up with any "ideal" solutions, so far following "ideas" where on the table:

• accept the fact that we can't do much and add junk description eg. @param somearg somearg
  • Drawback: junk in Javadoc comments
• having more complicated wording there "The somearg value"
  • Drawback: wouldn't improve much over previous solution whilst also might be not the best solution for projects that might be using non-english descriptions ?
• have a configuration property for missing property descriptions
  • Drawback: one more config property to support that doesn't add much value, but would "mitigate" issue of approach above - adding static complicated description text
• have a configuration property to disable adding of Javadoc params
  • Drawback: one more config property to support
• try to complicate logic a bit - apply "all or nothing" strategy: eg. check if number of Javadoc descriptions for constructor matches the number of arguments - add Javadoc, else skip it entirely
  • Drawback: might not be so obvious what is going on for users, why in certain cases Javadoc is generated and in the other cases is not
• some sort of combination of above

[joelittlejohn]

On reflection I think the way you have implemented this is correct. We should omit any param that has no description.

If you see a warning telling you that you have not documented some parameters, then this warning is accurate, and you can fix it by documenting the parameter (add title and/or description).

[unkish]

For a moment I've thought that people might start complaining about schema being an external to their project and them being unable/not allowed to modify it. But change wouldn't make it worse (granted that warning and not error will be emitted) as currently we produce Javadoc without @param description that also generates warning.

[joelittlejohn]

@unkish This is the last one for 1.2.0 I think. Could you rebase and I will merge?

[unkish]

An observation not related to given task. There has been a change https://github.com/joelittlejohn/jsonschema2pojo/blob/02d6017c08a092b72a177c4e5e6b9dc3a5d1124c/jsonschema2pojo-gradle-plugin/src/main/groovy/org/jsonschema2pojo/gradle/GenerateJsonSchemaJavaTask.groovy#L56 However configuration is defined as: https://github.com/joelittlejohn/jsonschema2pojo/blob/02d6017c08a092b72a177c4e5e6b9dc3a5d1124c/jsonschema2pojo-gradle-plugin/src/main/groovy/org/jsonschema2pojo/gradle/GenerateJsonSchemaJavaTask.groovy#L34 and setTargetVersion accepts JsonSchemaExtension (which is a implementation of GenerationConfig) https://github.com/joelittlejohn/jsonschema2pojo/blob/02d6017c08a092b72a177c4e5e6b9dc3a5d1124c/jsonschema2pojo-gradle-plugin/src/main/groovy/org/jsonschema2pojo/gradle/GenerateJsonSchemaJavaTask.groovy#L85

Is gradle doing some trickery that this won't be failing in runtime ?

UPD: Probably is fine as configuration = project.jsonSchema2Pojo