• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Tim Cooke
  • Devaka Cooray
  • Ron McLeod
  • Jeanne Boyarsky
Sheriffs:
  • Liutauras Vilda
  • paul wheaton
  • Junilu Lacar
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Piet Souris
  • Carey Brown
  • Tim Holloway
Bartenders:
  • Martijn Verburg
  • Frits Walraven
  • Himai Minh

Javadoc documentation??

 
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
hey,ranchers:
Do we need to generate the javadoc documentation for private classes and methods?
In my B&S specification, it says:
-------------------------------------------
...
Awkward or complex code should have descriptive comments, and javadoc style comments must be used for each element of the public interface of each class. You must create a full suite of documentation for the classes of the completed project. This must be generated using the tool "javadoc" and must be in HTML format. Provide javadoc documentation for all classes you write.
...
------------------------------------------

and it also says:
------------------------------------------
A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting.
------------------------------------------

thanks in advance
 
Ranch Hand
Posts: 1847
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
It's not stricly required, but I do write it anyway.

I write Javadoc for pretty much everything (including some class member variables) and have ANT set to generate for protected and more public only.

That should suffice the requirements (in fact it goes over them) as well as showing best practice (and working for the maintainability of the code, which depends on good documentation and coding style, which IMO includes complete developer documentation of private methods as well).

For the Javadoc style to follow, read the style guides and the JDK Javadoc.
There are conventions to be followed for things like the order in which exceptions are listed in Javadoc comments for example, which I'd not seen before.
 
And will you succeed? Yes you will indeed! (98 and 3/4 % guaranteed) - Seuss. tiny ad:
the value of filler advertising in 2021
https://coderanch.com/t/730886/filler-advertising
reply
    Bookmark Topic Watch Topic
  • New Topic