Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

B&S: What types do you comment with javadoc?

 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all,

my assignment says:


... javadoc style comments must be used for each element of the public interface of each class ...


To my opinion that means to provide javadoc comments for all public methods in all classes.

What about the other types? As far as I see we have these type that can be provided with javadoc comments:

  • javadoc Comments for Classes
  • javadoc Comments for Interfaces
  • javadoc Comments for Contructors
  • javadoc Comments for Methods
  • javadoc Comments for Exceptions
  • javadoc Comments for Variables


  • Shall we provide javadoc comments for all types? What about the private types?

    Regards,
    Darya
     
    Alex Belisle Turcot
    Ranch Hand
    Posts: 516
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi,


    Yes, I believe it means "comments for all public methods in all classes".

    That includes at least the public constructors, methods, variables (probably none). I would do it for interfaces also. Document exceptions for public methods. And I would also do it for the general comment of the class/interface.

    What's the rest of that sentence ?

    bye,
    Alex
    [ May 30, 2005: Message edited by: Alex Turcot ]
     
    Frans Janssen
    Ranch Hand
    Posts: 357
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi Darya,

    I have commented all methods (I think co-developers would also like to know what the private methods do), all classes and all non-private fields and variables.
    For each method I provided comment on all parameters, the return value and possible exceptions.

    Frans.
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Did you provide also the private javadoc comments in your HTML output ?

    Regards,
    Darya
     
    Frans Janssen
    Ranch Hand
    Posts: 357
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Did you provide also the private javadoc comments in your HTML output ?

    No, I didn't. I used the -package flag for generating the html files.

    Frans.
     
    • Post Reply
    • Bookmark Topic Watch Topic
    • New Topic