• 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:
  • Tim Cooke
  • Campbell Ritchie
  • Ron McLeod
  • Liutauras Vilda
  • Jeanne Boyarsky
Sheriffs:
  • Junilu Lacar
  • Rob Spoor
  • Paul Clapham
Saloon Keepers:
  • Tim Holloway
  • Tim Moores
  • Jesse Silverman
  • Stephan van Hulst
  • Carey Brown
Bartenders:
  • Al Hobbs
  • Piet Souris
  • Frits Walraven

Disallowed to use private inner classes?

 
Ranch Hand
Posts: 77
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
The reason I am asking is that I have this in my requirements:

The JAR file must have the following layout and contents in its root:
  • The a directory called docs, containing the following items at the top level:
  • ... A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting


  • Now, if I have a private inner class somewhere, this would force me to generate documentation right down to the private level, which I certainly not something I wish to do.

    Does anyone know if this is a problem?
    If it is, I guess I'll just make the class package private.
     
    Ranch Hand
    Posts: 194
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    I use some default access classes and no Javadoc is generated for them.

    I am wondering if that would be allowed. But if its part of the design and Javadoc does not document them, then thats not a problem I surpose.
     
    Ranch Hand
    Posts: 48
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    Hello there,

    The instructions do read "all classes and interfaces" so I'm taking it at face value and documenting everything. It's a little bit more writing, but I tend to write most of the comments first, so no big deal. I do, by the way, have private inner classes (ActionListeners.)

    javadoc has the -public, -protected, -package and -private switches to determine what javadoc generates documentation for. Per the previous comment, I'm thinking I have to use -private.

    Regards,
    Jay
    [ October 15, 2004: Message edited by: Jay Bromley ]
     
    Greenhorn
    Posts: 8
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    The following is from the documentation sub-section within the Application Overview of my instructions.

    The code itself should be as clear as possible; do not provide comments that do not add to the comprehensibility of the code. 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...



    I think commenting the 'public interface' is the way forward :-)
     
    James Turner
    Ranch Hand
    Posts: 194
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    Hi there,

    By saying:

    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.

    Then saying:

    Provide javadoc documentation for all classes you write...

    It is contradicting itself. Even so I think that only public interface classes and methods need to be documented with Javadoc, private methods and classes should be anonymous to the clients of the code in any respect, after all this is one of the main points of object orientation.

    James.
     
    Gaz Smith
    Greenhorn
    Posts: 8
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator

    It is contradicting itself.



    ..and not for the first time I'm sure you'll agree! :roll:

    I think this is the 'common sense' solution though. You could even document the decision to document!

    p.s. I'm currently reading Refactoring: Improving the Design of Existing Code by Martin Fowler. It's a good read that encourages the development of self describing code. i.e. Only put comments (non-javadoc) where necessary for clarity and if they're needed at all then the first step is probably to assess why the code is so complex as to not be readable. Bit off subject but this reminded me of it
    reply
      Bookmark Topic Watch Topic
    • New Topic