Documenting your work

From gvSIG CE Wiki

Jump to: navigation, search

Contents

Documenting the source code

As a developer, you have an increased responsibility to document your work by writing comments. The long-term maintainability of our source code depends on developers putting in those few extra minutes for this purpose.

SVN comments

Whenever you make an SVN commit, do not forget to add a line of comment that explains what you have done. This will be emailed to the developers mailing list and will be the basis on which other developers can understand and judge your changes/additions. It is essential for the quality of our software that this form of peer review can happen. If you do not comment your commits, you run a chance that they will be reversed.

Code commenting

Apart from providing a comment line when making an SVN commit, the primary way of documenting your source code is by putting comments into the Java source files. So far, the gvSIG CE source code is too sparsely commented and we urgently need to change this.

Some things to look out for when working with existing code:

  • Missing comments: Add them wherever you think they are missing. This is especially needed for uncommented Java classes and functions (assuming that you understand well what they do).
  • Spanish comments: Translate them if you know what they mean and directly commit to SVN.

Please help to continuously improve the situation by adding/improving comments whenever you can.

Javadoc

All class and function comments should follow the Javadoc syntax so that we can generate an API documentation from them. There is a nice Wikipedia article that explains this (simple) syntax. Every class and function should have a Javadoc style commment header. If you create your own classes, please keep this in mind. If you find a class or function that has no Javadoc comments, please add them.

Eclipse has built-in support for generating Javadoc HTML trees. If you have SVN write access, then you can help keeping the Javadoc pages up-to-date by performing these simple steps:

  1. Check-out the current Javadocs Eclipse project from https://gvsigce.svn.sourceforge.net/svnroot/gvsigce/trunk/docs/javadoc.
  2. Make your changes to the Java source files to add/improve the Javadoc comments.
  3. In Eclipse, choose "Project -> Generate Javadoc..." from the main menu.

This will bring up the Javadoc Generation wizard. To generate new Javadocs:

  1. Make sure that "Javadoc command" has been configured correctly to point to the javadoc binary in your JDK.
  2. Select the projects for which you have changed the Javadoc comments in the list.
  3. Leave the other two options to "(o) Public" and "(o) Use standard doclet", then press "Next >".
  4. On the second page, leave all settings as they are and press "Next >".
  5. On the final page, just press "Finish".
  6. Watch the Javadoc output in Eclipse's console for any errors or warnings.

If you get an error about "unmappable characters", run the wizard again, and on the third page add the following option:

 -encoding ISO-8859-1

(this is due to Spanish characters in the source files, which do not use UTF-8 encoding.)

Open the index.html page inside the javadoc_gvSIG project folder with a web browser and make sure that the result is acceptable. If it is, you can update the javadoc files by committing to the SVN.

To access the current Javadoc pages, go here (or here without redirection).

If you create new classes, or find existing classes, you can add some Javadoc skeleton comments to save you some typing work. There is an Eclipse plugin for just that job here. Just make sure to read the instructions and set it up correctly, so that it does not overwrite existing Javadoc comments!