Name: rmT116609 Date: 10/17/2003

A DESCRIPTION OF THE REQUEST :
It would be very helpful to have a Doclet that can produce Business Documentation out of Java source code (similar to the standard doclet that produces API docs for developers). I think of additional tags like

@biz_section Title of section
@biz_subsection Title of subsection
@biz_subsubsection Title of subsubsection
@biz_paragraph
etc. ...

that can occur in both class and method javadoc comments. the reason is, that the doclet should extract the info to create a business documentation that is not so class/method dependend. but usually, the developer has to write the business doc, too. so it would be the best way to write the same business doc into the code he/she is writting.

the doclet would then create the corresponding index, the sections incl. autonumbering and the related paragraphs. The titles of the sections would indicate to which section the following paragraphs would occur. same titles can occur multiple times, e.g:

/**
* @biz_section Performance Analysis
* @biz_paragraph The Performance Analysis is ...
*/
public class ...

/**
*@biz_section Performance Analysis
*@biz_subsection Calculations
*@biz_subsubsection Portfolio calculation
*@biz_paragraph To calculate a portfolio ...
*/
public void calculateRecord() {...

The section titles are not restricted to the same class but can refer to the same sections in other classes and their methods:

/**
* @biz_section Reporting
* @biz_paragraph Inspection of Portfolios can be ...
*/
public class ...

/**
*@biz_section Performance Analysis
*@biz_subsection Overviews
*@biz_subsubsection Success Report
*@biz_paragraph To display the result ...
*/
public void setupData() {...

would result in a business doc (here: XML to render later to PDF):

<bizdoc>
<section title="Performance Analysis">
    <section title="Calculations">
        <section title="Portfolio calculation">
            <paragraph>
            To calculate a portfolio ...
            </paragraph>
        </section>
    </section>
    <section title="Overviews">
<section title="Success Report">
   <paragraph>
To display the result ...
  </paragraph>
</section>
    </section>
</section>
<section title="Reporting">
    <paragraph>
    Inspection of Portfolios can be ...
    </paragraph>
</section>
</bizdoc>


JUSTIFICATION :
1. developer often has to write business doc, too
2. coding is mostly done due to business requirements
3. because of 1. and 2., the best way for the developer is, to include the
   business doc into the java source (just like the technical (API) doc).
   business requirements are often splitted into business objects and processing
   methods ... quite similar to classes/methods.
4. if requirements change, the developer changes the code and often does not
   change the business doc. if the business doc is very near to the code, the
   probability to adjust the business doc is very high.
5. generation of business doc would be automatic and always at current state -
   just like the API docs

the association to classes/methods is not for technical reasons but for easy documentation reasons. example:

the developer has to change a functionality "Calculate Portfolio Summary". This is a main section in the business doc. To implement the changes he has to adjust several classes and methods. He would then just add/change business documentation (if necessary) at the exact same classes/methods he changes (=> easy and fast adjustment of business doc). with the approach i posted above, he would use the same "biz_section" ("biz_subsection", etc.) titles in the various class/method comments to adjust the business documentation. after generating the business doc with javadoc (and this genious business doclet ;-) the resulting sections/subsections/etc. would not reflect any similarity to classes / methods.

in brief:
- write business doc during coding
- automatically generate business doc (without fixed 1:1 relations to classes/methods)


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
calling javadoc on java sources that have @biz_xxx javadoc tags would produce a (XML, HTML, PDF, ...) document with the business documentation.
ACTUAL -
so far, the standard doclet creates documentation for the standard javadoc tags that are tight to classes/methods/fields.

(Incident Review ID: 216238)
======================================================================