Joe Kesselman created XALANJ-2704:
-------------------------------------
Summary: Clean up our javadoc
Key: XALANJ-2704
URL: https://issues.apache.org/jira/browse/XALANJ-2704
Project: XalanJ2
Issue Type: Improvement
Security Level: No security risk; visible to anyone (Ordinary problems in
Xalan projects. Anybody can view the issue.)
Components: Documentation
Affects Versions: 2.7.3
Reporter: Joe Kesselman
Assignee: Gary D. Gregory
Maven, unlike Ant, defaults to running javadoc with {{doclint}} turned on, and
flags a metric buttload of problems in the javadoc comments.
Since that's a distraction from the maven port effort, I've turned off
{{doclint}} in the pom.xml for now.
However, it is quite correct: A lot of our javadoc is really not up to modern
standards.
Much of it can actually be improved by the simple expedient of deleting it, and
letting javadoc automatically reference the doc for the interface/class
artifact we are inheriting from. There's also the option of having local
javadoc comments that use ${@inheritDoc} to explicitly copy down the inherited
information, letting us then add whatever is different about this
implementation.
It would be nice to be able to turn {{doclint}} back on without seeing errors
in the maven build, hence this work item. I'd suggest whoever works on it
actually start by re-enabling {{doclint}} and using its complaints to guide
repairs.
Note that much of this *could* be within the scope of someone relatively new to
the Xalan codebase, and would be a (panfully?) deep introduction to the overall
structure of Xalan's code. So if we have a Really Enthusiastic newcomer, this
might be a good place for them t start.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
