Re: [Cdk-devel] [Javadoc] A simple way to improve documentation.

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

On Saturday 29 May 2004 19:46, M.Le_maudit wrote:
> > > So, in order to help developers writing - let's be ambitious ;-) -
> > > *excellent* Javadoc comments, I though it might be interesting to
> > > develop Javadoc comment templates.
> >
> > What would these templates look like? There are jEdit plugins which can
> > add templates too, but I really dislike JavaDoc like
> >
> > /**
> >  * Description of method X.
> >  *
> >  * @param x first parameter
> >  */
>
> This is exactly the kind of comment I would like to avoid.
>
> > Because this will not given any information other than the obvious, and
> > make it impossible to automatically detect where documentation is
> > missing.
>
> We share the same point of view.
>
> > > These comment templates might be used to document
> > > the CDK project, but they also might be helpful for the other related
> > > projects, such as JChemPaint, Jmol, and the most recent QSAR.
> > >
> > > These templates would at least bring these benefits:
> > > - homogenous documentation for all the previously mentioned projects.
> > > - no need to look for Javadoc's expected information: the complete
> > > documentation requirements would be available through these templates.
> >
> > I do not understand your second benefit...
>
> As you're not able to read my mind, I understand that you do not understand
> this second benefit, and that's why I will give you more explanations about
> it. :)
>
> > > What do you think about this idea?
> >
> > What would a template for CDK look like?
>
> Excellent question. Let me show you what I have in mind.
>
> A comment template would be a *file* containing the skeleton of the
> Javadoc comment.
>
> This skeleton would be composed of several parts.
>
> Let's take the example of a class field comment:
>
> If you look at the Javadoc's requirements published by sun, you'll find
> that 3 sections are expected for a class field comment:
>
> 1- a section to explain what the field models
> 2- a section to give all valid and invalid values for the field
> 3- a section to explain the behaviour of the object if the field is <null>
>
> Using these information, it is possible to write this kind of comment
> template:
>
> [comment template start]
> /**
>  * <!-- -----------------------------------------------------------------
>  * Sum up phrase
>  *  Required
>  *   A phrase to summarize what the field models.
>  *
>  * Executive summary
>  *  Optional - use it only if the sum up phrase is not complete.
>  *  A paragraph to explain what aspect(s) of the object this
>  *   this field models. Here you may specify business and/or
>  *   programming modelling aspects.
>  *
>  * ------------------------------------------------------------------ -->
>  * <!--
>  * <p>[sum up phrase.][executive summary paragraph.]</p>
>  * -->
>  *
>  * <!-- -----------------------------------------------------------------
>  * Valid range of values
>  *  Required
>  *   Give the field's valid value(s) and/or valid value(s) range(s).
>  *
>  * Invalid range of values
>  *  Required
>  *   Give the field's invalid value(s) and/or invalid value(s) range(s)
>  *   and specify how the object will behave in such a case.
>  *
>  * Null value
>  *  Required - for all reference fields
>  *  Unused   - for non reference fields
>  *   Write a statement concerning whether this value may be null, and
>  *   how this object will behave in such a case.
>  *
>  * ------------------------------------------------------------------ -->
>  * <!--
>  * <p><b>Values</b>:
>  *  <ul>
>  * -->
>  * <!--
>  *   <dt><code>Valid value(s)</code>:</dt>
>  *   <dd>
>  *    <li>[valid value(s) range(s) paragraph.]</li>
>  *   </dd>
>  * -->
>  * <!--
>  *   <dt><code>Invalid value(s)</code>:</dt>
>  *   <dd>
>  *    <li>[invalid value(s) range(s) paragraph.]</li>
>  *   </dd>
>  * -->
>  * <!--
>  *   <dt><code>Null value</code>:</dt>
>  *   <dd>
>  *    <li>[null value behaviour paragraph.]</li>
>  *   </dd>
>  * -->
>  * <!--
>  *  </ul>
>  * </p>
>  * -->
>  */
> //DOCME Add sum up phrase.
> //DOCME Add executive summary.
> //DOCME Add range of valid values.
> //DOCME Add range of invalid values.
> //DOCME Add null value behaviour.
> [comment template end]
>
> As you've probably notice, the use of this template will require discipline
> from the developer because if this template is copied/pasted *as is* in the
> source code, It will result in no documentation generated by the Javadoc
> tool and as you said, it will be *impossible to automatically detect where
> documentation is missing*.

Indeed. Good, did not thing of this...

> So, the developer will have the responsibility to use the template only if
> his (or her) intention is to document a class field. To help developers to
> know if documentation is missing, I have added a *TODO like* section at the
> end of the template.
>
> It's easy to configure a Task manager to recognise a TODO, a FIXME, a XXX
> or a DOCME tag, so if an absent minded developer pastes this template and
> forget to document the class field, it will be easily possible to find
> missing documentation and then remove the undocumented comments or document
> them.
>
> Now, a few words about how to use this kind of template:
>
> 1- copy/paste the template where necessary (just before the field to
> document)
> 2- read the first section (sum up and executive summary)
> 3- replace *[sum up phrase.]* and *[executive summary paragraph.]* with the
> appropriate information.
> 4- remove the enclosing html comment tags (<!-- and -->)
> 5- remove the descriptive html commented out section if the comment
> information are complete. the section is enclose by this kind of tags :
> <!-- -----------------------------------------------------------------
> and
> ----------------------------------------------------------------- -->
> 6- remove the corresponding DOCME tag line
> 7- do the same for all the other sections.
>
> At the end you will obtain this kind of Javadoc comment:
>
> [resulting comment start]
> /**
>  * <p>My sum up phrase. The complete executive summary paragraph.</p>
>  *
>  * <p><b>Values</b>:
>  *  <ul>
>  *   <dt><code>Valid value(s)</code>:</dt>
>  *   <dd>
>  *    <li>My valid value(s) range(s) paragraph.</li>
>  *   </dd>
>  *   <dt><code>Invalid value(s)</code>:</dt>
>  *   <dd>
>  *    <li>My invalid value(s) range(s) paragraph.</li>
>  *   </dd>
>  *   <dt><code>Null value</code>:</dt>
>  *   <dd>
>  *    <li>My null value behaviour paragraph.</li>
>  *   </dd>
>  *  </ul>
>  * </p>
>  */
> [resulting comment end]
>
> Now imagine that the developer only have partial information.
> Let's say that he (she) doesn't know the <null> value behaviour.
>
> Following the 7 steps given previously would result in:
>
> [resulting partial comment start]
> /**
>  * <p>My sum up phrase. The complete executive summary paragraph.</p>
>  *
>  * <!-- -----------------------------------------------------------------
>  * Valid range of values
>  *  Required
>  *   Give the field's valid value(s) and/or valid value(s) range(s).
>  *
>  * Invalid range of values
>  *  Required
>  *   Give the field's invalid value(s) and/or invalid value(s) range(s)
>  *   and specify how the object will behave in such a case.
>  *
>  * Null value
>  *  Required - for all reference fields
>  *  Unused   - for non reference fields
>  *   Write a statement concerning whether this value may be null, and
>  *   how this object will behave in such a case.
>  *
>  * ----------------------------------------------------------------- -->
>  * <p><b>Values</b>:
>  *  <ul>
>  *   <dt><code>Valid value(s)</code>:</dt>
>  *   <dd>
>  *    <li>My valid value(s) range(s) paragraph.</li>
>  *   </dd>
>  *   <dt><code>Invalid value(s)</code>:</dt>
>  *   <dd>
>  *    <li>My invalid value(s) range(s) paragraph.</li>
>  *   </dd>
>  * <!--
>  *   <dt><code>Null value</code>:</dt>
>  *   <dd>
>  *    <li>[null value behaviour paragraph.]</li>
>  *   </dd>
>  * -->
>  *  </ul>
>  * </p>
>  */
> //DOCME Add null value behaviour.
> [resulting partial comment end]
>
> By doing this, the developer will :
> - provide documentation
> - know and tell that some pieces of information are missing
> - know and tell which pieces of information are missing
>
> This will help other developers to know that things are missing. Then if
> someone has the missing information he (she) will be able to correctly
> document the Javadoc comment and then increase the documentation's quality.
>
> As you've probably noticed, the most important point it is not how the
> template would look like but how the developer will use it.
> This point will make the difference between good and excellent Javadoc
> comments.
> Of course, as I said, this will require discipline... ;-)
>
> I hope this will answer your questions. :)

Yes, it does...

In general I agree that the JavaDoc needs to be improved... But I'm still 
eluctant to add this much templates to CVS... 
1. all this templates makes it difficult to browse the souce file
2. who has the time to fill these templates

Can we make this template the default format, but keep it outside the 
sourcefiles? But still have a method to see which bits of the template are 
and are not written? For example, can we use custom XML elements, to
make certain parts as the "Executive Summary" without it ending up in the
HTML version of the JavaDoc?

Egon