Larry wrote: "IMO Javadoc comments should be short statements of > purpose. They shouldn't talk about algorithms, but should document > anything unusual about parameters. For example, Object parameters are > used in RenderManager methods, but it isn't documented what Objects > are acceptable."
Excellent feedback Larry. Thank you. Here are a couple of sample Javadoc comments that I wrote. Can you tell me if they meet your description, or if they are too wordy: /** * Initialized this plug-in. This method installs the IRendererFactoryTool implementation * passed to the constructor of this object in the TaskFrame that appears * when OpenJUMP is first started. It also installs a listener so that the same action * can occur when subsequent TaskFrames are created. */ /** * Moves an object up in the list of objects that get rendered above * Layerable objects. This means the object will get painted after the * objects underneath it in the list and will appear "above" them in * the LayerViewPanel. If the object passed as an argument is already at * the top of the list an exception will be thrown. * * @throws IndexOutOfBoundsException Thrown if the object passed as a parameter * is already at the top of the list. */ Thanks again. SS On 6/25/07, Larry Becker <[EMAIL PROTECTED]> wrote: > Hi SS, > > OK by me. IMO Javadoc comments should be short statements of > purpose. They shouldn't talk about algorithms, but should document > anything unusual about parameters. For example, Object parameters are > used in RenderManager methods, but it isn't documented what Objects > are acceptable. > > regards, > Larry > > > On 6/25/07, Sunburned Surveyor <[EMAIL PROTECTED]> wrote: > > I'm currently adding Javadoc comments and anylizing methods for unit > > testing in my code for OpenJUMP's pluggable rendering system. I have a > > question about commits to the OpenJUMP SVN that I wanted to run by you > > guys: > > > > Does anyone have a problem with me adding Javadoc comments to public > > methods currently without javadoc comments in existing JUMP classes > > that I work with? For example, the RenderingManager class has several > > public methods with no Javadoc comments. > > > > I know I can get a little comment happy, so I thought I would ask hear > > before I submit anything. I promise I will keep any new Javadoc > > comments as terse as possible. :] > > > > The Sunburned Surveyor > > > > ------------------------------------------------------------------------- > > This SF.net email is sponsored by DB2 Express > > Download DB2 Express C - the FREE version of DB2 express and take > > control of your XML. No limits. Just data. Click to get it now. > > http://sourceforge.net/powerbar/db2/ > > _______________________________________________ > > Jump-pilot-devel mailing list > > Jump-pilot-devel@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > > > > > -- > http://amusingprogrammer.blogspot.com/ > > ------------------------------------------------------------------------- > This SF.net email is sponsored by DB2 Express > Download DB2 Express C - the FREE version of DB2 express and take > control of your XML. No limits. Just data. Click to get it now. > http://sourceforge.net/powerbar/db2/ > _______________________________________________ > Jump-pilot-devel mailing list > Jump-pilot-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel > ------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Jump-pilot-devel mailing list Jump-pilot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/jump-pilot-devel
