>* @param p1 a <code>Param1[]</code> value
I don't find this kind of generation (above) useful. The javadoc generator already
knows the types from the parameters and publishes these in the resultant javadoc. I
think the param fields should be initially blank as the automatic comments just
provide redundant information, that which would already be in the docs and makes it
harder to notice which javadocs haven't been completed.
Paul.
"Guillaume Berche"
<guillaume.berche@eloquant. To:
<[EMAIL PROTECTED]>
com> cc:
Sent by: Subject: [Eap-features]
Javadoc autogeneration/update: experience from emacs JDE
[EMAIL PROTECTED]
tbrains.com
31/07/2002 08:58
Please respond to
eap-features
Hello
I agree with the suggestions made on this list concerning javadoc comments
autogeneration from method skeletton, update when method changes (including
in the method prototype change refactoring that should proprose to
add/remove/update javadoc tags as required)
One of the nicest features of emacs JDE I was missing from IDEA is precisely
this one. The rest of this mail helps to contribute to the IDEA javadoc
generation useability from the experience from JDE which is particularly
strong in this area.
This is how things were designed by JDE developers, I find it very well
thought:
Step 1: write method/constructor/field/class prototype.
private static final int MAX_PARAMS = 2;
private int nbParams_;
public String newMethod(Param1 [] p1, AnotherParam2 p2) throws Exception {
}
public TestExecutableRecorder() {
}
Step2: press "generate javadoc"
/**
* Describe constant <code>MAX_PARAMS</code> here.
*
*/
private static final int MAX_PARAMS = 2;
/**
* Describe variable <code>nbParams_</code> here.
*
*/
private int nbParams_;
/**
* Describe <code>newMethod</code> method here.
*
* @param p1 a <code>Param1[]</code> value
* @param p2 an <code>AnotherParam2</code> value
* @return a <code>String</code> value
* @exception Exception if an error occurs
*/
public String newMethod(Param1 [] p1, AnotherParam2 p2) throws Exception {
}
Note the "an" prefix (instead of "a") to the param p2 because the class
starts with the letter A.
/**
* Creates a new <code>TestExecutableRecorder</code> instance.
*
*/
public TestExecutableRecorder() {
}
The generated javadoc is configureable with a template.
Step 3: press "generate javadoc" => says "javadoc is up-to-date"
Step 4: modify prototype
public String newMethod(Param1 [] p1, AnotherParam2 p2, ThirdParamType p3)
throws NewException {
}
Step 5: press "generate javadoc" => says "do you want to delete "newMethod"
previous documentation? Answer no or yes (then get back to effect of step2)
Step 6: press "update javadoc"
=> Proposes the following options
"method `newMethod' has 3 documentation errors:
* Missing @param tag for `p3'
* Missing @exception tag for `NewException'
* Extra @exception tag `Exception' (maybe not an error)
[f]-try to fix [p]-check previous [n]-check next [q]-quit"
Next check allows you to iteratively check all javadoc comments in the
class.
Step 7: when editing the javadoc press "auto-fill" and this breaks line as
appropriate (I hope my mailer will not autobreak lines in this example :-)
/**
* Describe <code>newMethod</code> method here.
* @param p1 a <code>Param1[]</code> value a very very long line gets
broken while preserving others
* @param p2 an <code>AnotherParam2</code> value
* @return a <code>String</code> value
* @exception Exception if an error occurs
*/
becomes
/**
* Describe <code>newMethod</code> method here.
* @param p1 a <code>Param1[]</code> value a very very long line gets
broken
* while preserving others
* @param p2 an <code>AnotherParam2</code> value
* @return a <code>String</code> value
* @exception Exception if an error occurs
One thing still missing is (as was suggested on this list) preserving line
breaks on HTML tags such as the following
/**
* <code>doIt</code> is used in one of the following cases <OL>
* <LI>in case X</LI>
* <LI>in case Y</LI>
* </OL>
*/
I hope this experience with JDE can help,
Guillaume.
_______________________________________________
Eap-features mailing list
[EMAIL PROTECTED]
http://lists.jetbrains.com/mailman/listinfo/eap-features
--
This e-mail may contain confidential and/or privileged information. If you are not the
intended recipient (or have received this e-mail in error) please notify the sender
immediately and destroy this e-mail. Any unauthorized copying, disclosure or
distribution of the material in this e-mail is strictly forbidden.
_______________________________________________
Eap-features mailing list
[EMAIL PROTECTED]
http://lists.jetbrains.com/mailman/listinfo/eap-features
