search

frankframework / frank-doc

Frank!Doc
https://frankdoc.frankframework.org
Apache License 2.0
4 stars 5 forks source link

Support {@value } tags in javadoc #144

Closed gvanbrakel closed 1 year ago

gvanbrakel commented 1 year ago

With the conversion from IbisDoc to JavaDoc the {@value } tag is introduced, to refer to constants in the java code. The FrankDoc generator should resolve these values. See https://frankdoc.frankframework.org/#!/All/LocalFileSystemPipe

image

mhdirkse commented 1 year ago

I think that the doclet API does not resolve the {@value ...} tags automatically. I understood that the syntax applied now in the iaf sources does work in the JavaDocs. The resolving is probably a feature of the standard doclet. If it were built-in to the doclet API, the Frank!Doc would already resolve {@value ...}. I have to code the resolution of the {@value ...} into the Frank!Doc.

Second, The javadoc tool has some options that are applied to all doclets. One of them is -private, which causes private elements in the read code to be seen by the doclet. We do not set this option now. It has to be enabled and then the existing doclet code should be edited to produce the same output as before.

For the implementation, I think that the wrapper API's FrankClass interface should have a new method resolveValue() that takes the argument inside a {@value ...}. Then the model should parse the {@value ...} patterns within descriptions and default values.

I think I should do it in the following sequence:

  1. Implement FrankClass.resolveValue() and test it with public static final members and with public enum constants.
  2. Add the -private option and adjust the Frank!Doc code until there are no changes in the produced output. Test that FrankClass.resolveValue() can now access private elements.
  3. Implement resolving {@value ...} in the model.

I will have a look at the source code of the standard doclet if I can find it. If I can read that code, I may get ideas for the implementation.

gvanbrakel commented 1 year ago

I think your approach is basically OK, with the remark that 'resolveValue()' will probably already exist somewhere in javadoc. For a hint, see https://stackoverflow.com/questions/21363175/javadoc-constant-field-values-for-strings

mhdirkse commented 1 year ago

From your link I understand that resolveValue() exists in the standard doclet. In the Stack Overflow post, the standard doclet is being subclassed why the Frank!Doc is a doclet I created from scratch. I could not find the source code of the standard doclet easily, so I think I will program it myself. I already have code to get the value of an annotation, and I see that a constant is in a Doclet API class called FieldDoc. It should not be too difficult to get the value from a Java constant.