From: Peter Murray-R. <pm...@ca...> - 2004-05-29 15:52:01
|
At 15:07 29/05/2004 +0200, eg...@sc... wrote: >Quoting "M.Le_maudit" <mle...@us...>: > > For a while, I've been reading CDK, JChemPaint and related projects' > source > > code and as mentioned on the CDK website, it is obvious that an effort may > > be made to improve documentation available through Javadoc comments. Am I > > wrong? ;-) > >No, JavaDoc is important... Agreed > > > 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 > */ > >Because this will not given any information other than the obvious, and >make it impossible to automatically detect where documentation is missing. I agree. However I cannot easily see what a template would look like beyond the default which is: /** 1-line description * * description ... * @param @throws @return */ I have tried to train myself into always putting these into what I write with some additions the 1-liner has to end with a period and have no other punctuation, otherwise javadoc throws tens of warnings. This drives me wild! The description should ideally have an example of how to call the method. I don't always manage this @param should give restrictions on parameter if appropriate. This is particularly useful with symbolic values (in uppercase) @throws should give some indications of what might go wrong, but when this bubbles up from lower routines this is almost impossible @return should indicate limits on the return value, especially whether it can be null or a zero-length object > > > 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... > > > What do you think about this idea? > >What would a template for CDK look like? P. > Peter Murray-Rust Unilever Centre for Molecular Informatics Chemistry Department, Cambridge University Lensfield Road, CAMBRIDGE, CB2 1EW, UK Tel: +44-1223-763069 |