From: Egon W. <e.w...@sc...> - 2005-06-24 07:27:54
|
Hi all, I just spend 30 minutes cleaning up bad JavaDoc, which is still autogenerated by some IDE's !!!! Just to be able to see wether JavaDoc two bugs are still present! I've must have asked several times now, and this is the last time I will do it. Please do not use your IDE to create these bloody JavaDoc fragments: - @created - and JavaDoc descriptions like: Documentation of this class/method etc... Again: @created is NOT a valid JavaDoc tag; and those autogenerated descriptorns completely mess up quality control ! Next time I will have to do this I'll seriously explore setting up a commit block for commits having these characteristics, instead of having to manually clean up this issues and having to write once more to the mailing list. I know documentation is of lowest priority to most, but please do not make it more difficult to those who do care at least a bit... Thanx Egon PS. If I sound a bit pissed off, I am... partly caused by the bloody hot room I'm working in :( |
From: Egon W. <e.w...@sc...> - 2005-06-24 07:42:05
|
On Friday 24 June 2005 09:31 am, Egon Willighagen wrote: > I just spend 30 minutes cleaning up bad JavaDoc, which is still > autogenerated by some IDE's !!!! Just to be able to see wether JavaDoc two > bugs are still present! Oh, and the remaining warning by JavaDoc are: ================================================================ [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/AtomType.java:330: warning - @param argument "electronValency" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/AtomType.java:342: warning - @param argument "electronValency" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/Polymer.java:82: warning - @param argument "oMonomer" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/Polymer.java:147: warning - @param argument "cName" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/Polymer.java:232: warning - Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, package, class/interface. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/Polymer.java:241: warning - Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, package, class/interface. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/Strand.java:184: warning - Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, package, class/interface. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/Strand.java:195: warning - Tag @author cannot be used in method documentation. It can only be used in the following types of documentation: overview, package, class/interface. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/DrawingPanel.java:44: warning - Tag @see: reference not found: JChemPaintViewerPanel [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/DrawingPanel.java:59: warning - @param argument "jcpm" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintEditorPanel.java:86: warning - Tag @see: reference not found: JChemPaintViewerPanel [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintEditorPanel.java:325: warning - @param argument "showToolbar" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintEditorPanel.java:347: warning - @param argument "showToolbar" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintEditorPanel.java:429: warning - @param argument "jchemPaintModel" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintModel.java:323: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintModel.java:345: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintModel.java:354: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintModel.java:291: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintModel.java:374: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintModel.java:307: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/JChemPaintModel.java:216: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/ToolBarMaker.java:48: warning - Tag @see: reference not found: JChemPaintViewerPanel [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/action/MenuBarAction.java:44: warning - @created is an unknown tag. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/applet/JChemPaintAbstractApplet.java:160: warning - @param argument "theModel" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/applet/JChemPaintViewerOnlyApplet.java:118: warning - @param argument "atomNumbers" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/dialogs/InsertFromSmiles.java:74: warning - @param argument "jcp" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/dialogs/JavaHelpDialog.java:59: warning - @param argument "fr" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/dialogs/JavaHelpDialog.java:59: warning - @param argument "helpfile" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/dialogs/TextViewDialog.java:59: warning - Tag @see: missing '#': "TextViewDialog(JFrame, String, Dimension, boolean, int, int)" [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/dialogs/TextViewDialog.java:66: warning - Tag @see: missing '#': "TextViewDialog(JFrame, String, Dimension, boolean, int, int)" [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/dialogs/TextViewDialog.java:73: warning - Tag @see: missing '#': "TextViewDialog(JFrame, String, Dimension, boolean, int, int)" [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/applications/jchempaint/dnd/JCPTransferHandler.java:46: warning - @cdk.creator is an unknown tag. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/atomtype/HybridizationMatcher.java:72: warning - @param argument "atomContainerc" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/atomtype/HybridizationStateATMatcher.java:75: warning - @param argument "atomContainerc" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/geometry/GeometryTools.java:366: warning - Tag @see: missing '#': "get2DCenter(AtomContainer container)" [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/geometry/GeometryTools.java:366: warning - Tag @see: missing '#': "translate2DCentreOfMassTo(AtomContainer atomCon, Point2d p)" [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/geometry/ZMatrixTools.java:60: warning - @cdk.dict is an unknown tag. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/graph/SpanningTree.java:131: warning - @return tag has no arguments. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/graph/SpanningTree.java:131: warning - @return tag cannot be used in method with void return type. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/io/PDBReader.java:353: warning - @param argument "oFile" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/modeling/forcefield/AngleBending.java:429: warning - @param argument "coords3d" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/modeling/forcefield/Torsions.java:284: warning - @param argument "coords3d" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/modeling/forcefield/VanDerWaalsInteractions.java:497: warning - @param argument "coords3d" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/qsar/model/R/CNNClassificationModel.java:420: warning - @param argument "filename" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/qsar/model/R/CNNRegressionModel.java:419: warning - @param argument "filename" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/qsar/model/R/LinearRegressionModel.java:369: warning - @param argument "filename" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/qsar/model/R/PLSRegressionModel.java:291: warning - @param argument "filename" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/qsar/model/R/RModel.java:196: warning - Tag @link: reference not found: RModel.saveModel [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/qsar/model/R/RModel.java:196: warning - @param argument "modelName" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/ringsearch/SSSRFinder.java:75: warning - Tag @link: can't find SSSRFinder(Molecule) in org.openscience.cdk.ringsearch.SSSRFinder [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/ringsearch/SSSRFinder.java:83: warning - @param argument "mol" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/ringsearch/SSSRFinder.java:189: warning - @param argument "mol" is not a parameter name. [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/smiles/smarts/SMARTSParser.java:77: warning - Tag @see: reference not found: org.openscience.cdk.test.smiles.smarts.ParserTest [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/tools/SaturationChecker.java:419: warning - Tag @see: reference not found: org.openscience.cdk.test.limitations.tools.SaturationCheckerTest [javadoc] /home/egonw/data/Projects/SourceForge/CDK/cdk/src/org/openscience/cdk/tools/manipulator/AtomTypeManipulator.java:52: warning - @param argument "at" is not a parameter name. ================================================================ And these are just the syntax warnings and do not include many, many other JavaDoc errors that can occur. If you're interested in cleaning up CDK's JavaDoc, please run: > ant -f javadoc.xml html > ant -f javadoc.xml doccheck-all The latter requires you to download the doccheck jar from [1] which is free but cannot be distributed in CDK's CVS. It should be placed in cdk/develjar. Egon 1. http://java.sun.com/j2se/javadoc/doccheck/ |
From: Peter Murray-R. <pm...@ca...> - 2005-06-24 14:57:04
|
At 08:31 24/06/2005, Egon Willighagen wrote: >Hi all, > >I just spend 30 minutes cleaning up bad JavaDoc, which is still autogenerated >by some IDE's !!!! Just to be able to see wether JavaDoc two bugs are still >present! I sympathize! The problem is that any error seems to generate several pages of errors. I would like to meet the guy who decided on the punctuation rules for javadoc - essentially if you have any punctuation in the summary line other than a period is likely to crash. I try to work so that javadoc throws no errors because it's easy for errors to get hidden. P. Peter Murray-Rust Unilever Centre for Molecular Informatics Chemistry Department, Cambridge University Lensfield Road, CAMBRIDGE, CB2 1EW, UK Tel: +44-1223-763069 Fax: +44 1223 763076 |