Where to add javadoc in an open source Java project looking for good conventions:
- every public, package, private scope for class and members?
- every public scope for class and members?
- every important public scope for class and members?
Javadoc, e.g. in the (oracle) String class, occurs with public methods. For private ones, it appears as a block comment.
- What's the convention? Or maybe each JDK provider has its own? Do any of you have a link to the convention for java documentation question with rules, suggestions?
In my opinion, documentation should be written for all public class components. A block comment above the element should be created for private classes.
With javadoc, you can generate HTML documentation with:
- Generate documentation for Java source code and save the result in a directory: javadoc -d path / to / directory / path / to / java_source_code
- Generate documentation with a specific encoding: javadoc -docencoding UTF-8 path / to / java_source_code
- Generate documentation excluding some packages: javadoc -exclude package_list path / to / java_source_code
so the more there is in the code on the public elements - the better.
2. W którym momencie tworzenia kodu powinno tworzyć się dokumentację? Od razu przy tworzeniu jego elementów czy można poczekać i zacząć tworzyć dokumentację po jakimś czasie?
3. Czy istnieją narzędzia ułatwiające tworzenie dokumentacji? Np. pluginy pod IDE (InteliJ Idea lub Eclipse).
4. Another clean code rule says that the code should document itself. So there is no point in putting redundant code comments inside the methods.