@requiredParam and @optionalParam tags
Dear all,
I tried to implement two additional tags that should be used to identify required and optional parameters. First I thought this must be easy because it should be only a slight extension to the original @param tag.
However, I do not see a possibility to leverage the origninal param tag class. It would be important to reuse the original class because the processing of inlined tags is complicated.
The problem boils down to that in the API of the toString method of the taglet I get no Doc parameter but the ParamTagImpl needs a Doc. In addition the Comment class that also includes a lot of logic concerning the processing of inlined tags also needs a doc.
Can anyone help me with this problem? Maybe someone has already such tags / taglets.
--Stefan
> Aren't all parameters required in Java?
>
> I have added custom tags to JavaDoc successfully
> several times, but I'm not sure I understand your
> problem enough to provide help. Could you explain a
> little bit more about what these tags are and how you
> want them to appear in the javadocs?
The new (or modified) tag for parameters should indicate if a parameter is required, i.e. must not be null, or if it is optional, i.e. may be null. In addition, a similar mechanism should be applied for return values, i.e. to indicate if a return value is guaranteed not to be null or if it may be null. (cf. Design by Contract)
The generated HTML should clearly present that information, for example by coloring the parameters and return values or by adding additional text.
For the source I see at least two possibilities:
1.
/**
* A method with an required and an additional
* parameter. The return value is optional.
*
* @requiredParam aParam1 The first parameter.
* @optionalParam aParam2 The second parameter.
* @optionalReturn The return value.
*/
I would favour the first variant but I think it would break tools that check the JavaDoc for completeness.
2.
/**
* A method with an required and an additional
* parameter. The return value is optional.
*
* @param aParam1 {@req} The first parameter.
* @param aParam2 {@opt} The second parameter.
* @return {@opt} The return value.
This would work but there I have only the possibility to add some additional text. I think it would not be possible for example to color the output "aParam1" and "aParam2" in the generated HTML.
