= Some Javadoc Research [] (+)

 INTRODUCTION

   javadoc is the tool which extracts documentation from java code source files and
   transforms this into HTML. This file is about some research of the best ways
   to use javadoc. It would be pleasant to be able to transform javadoc documentation
   comments into formats other than HTML such as docbook xml. It is possible that by
   using a different 'doclet' this may be possible. 

   The basic problem with javadoc is that it allows HTML tags within the actual 
   documentation which is a really bad idea.  Also, the whole idea of having documentation
   withing code files is really bad to, for the simple reasons, that a) programmers dont
   tend to think in terms of explaining what they are doing and b) it looks horrible
   to put examples of code within code files, and for this reason javadoc discourages
   documenters from including examples in their documentation which is somewhat sad.

   

 SOME RESEARCH
 
  * The JavaDoc Web Home |http://java.sun.com/j2se/javadoc/|
     The javadoc tool home-page on the Sun Micro-systems site.

  * Quick Reference |http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/javadoc.html#javadoctags|
     This is the page and section which contains a reference list of what 'tags'
     (ie @tagname) are allowable in javadoc comments. Custom tags are also possible
     with the 'taglet' api. This page is oriented towards Microsoft Windows.
     
  * Examples |http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#examples|
    This document actually contains examples of javadoc comments. I believe that it is
    part of a larger document which describes standard practices at Sun Microsystems
    for writing javadoc comments

  * Javadoc to DocBook XML |http://www.dbdoclet.org/|
    This is the home of a doclet which makes Docbook xml from javadoc comments