Granny's Programming Pearls
"inside of every large program is a small program struggling to get out"
JavaRanch.com/granny.jsp
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Listener classes + javadoc Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Listener classes + javadoc" Watch "Listener classes + javadoc" New topic
Author

Listener classes + javadoc

Luiz Reginaldo Curado
Ranch Hand

Joined: Jan 19, 2006
Posts: 108
Hi all!

Just another question about the assignment. I have some listeners into my gui, as CloseListener, SearchListener, etc. Because of this classes are internal classes, I am not generating the javadoc for it - but in the source code the class is javadoc commented.

What do you think? I have to generate the javadoc for the Listeners classes too???
Lucy Hummel
Ranch Hand

Joined: Apr 07, 2005
Posts: 232
Hi,

I comment them.


----------------------------------<br />| SCJP, SCWCD, SCBCD, SCEA, SCJD |<br />----------------------------------
Luiz Reginaldo Curado
Ranch Hand

Joined: Jan 19, 2006
Posts: 108
Hi, Hummel.

I commented it too. But do you have generated the javadoc htmls for this classes?
Romeo Son
Ranch Hand

Joined: Mar 12, 2007
Posts: 92

Hi,

In my opinion, private members of a class do not need JavaDoc. I would generate JavaDoc for the public listener interface but not for its private inner classes implementations.
I suppose your CloseListener is declared as a public interface, right?
[ April 26, 2007: Message edited by: Romeo Son ]

SCJP 1.4, SCJD, OCE EJBD 6
Luiz Reginaldo Curado
Ranch Hand

Joined: Jan 19, 2006
Posts: 108
Hi, Romeo.

I declared my listener implementation class as a inner class, and with the private modifier. It did not appear in the javadoc.

So, I changed this class to public modifier. It then appear in the javadoc. This is not the best approach, but my assignment says that I must generated javadoc for all classes... So, I cannot leave this class without the javadoc...

In the assignment, the MUST can stole you precious marks...

Regards,

Luiz Reginaldo
Lucy Hummel
Ranch Hand

Joined: Apr 07, 2005
Posts: 232
Hi,

I checked my assignment and I found the requirement to add JavaDoc for all classes that is why I publish also all private classes and method to JavaDoc.
Romeo Son
Ranch Hand

Joined: Mar 12, 2007
Posts: 92

Hi Luiz,

Making an inner private class public just for the sake of the JavaDoc, doesn't seem to me the best approach. You make it public only and only if you want to be seen from other parts of your application. Otherwise you hide it by making it private.

Then I think that in JavaDoc only the public API is of interest, not the implementation, that must be hidden.

Let's take for example Sun's own code.
I took a look at their JTable implementation. I have found in it an interface Resizable2 without any comments. Then I have found another private inner class ThreadSafePrintable, that is fully commented, but that doesn't appear in Sun's JavaDoc.

javadoc tool has some options, public, protected, package and private. Try to generate your JavaDoc with -private option, see if it works. (Ant has it as well)

I think any approach will be accepted, if you mention it in choices.txt.

Romeo
[ May 06, 2007: Message edited by: Romeo Son ]
Lucy Hummel
Ranch Hand

Joined: Apr 07, 2005
Posts: 232
Hi Romeo,

I think we misunderstood each other.

I did not make my inner class public. These class are private, the same applies for method that should be hidden because ... ( you know why )

I change in my ant-script so that the private classes and method and class members are published to JavaDoc.

So I exactly did what you suggested.

We agree on that!

Anyway, thanks for taking care
Dalton Filho
Greenhorn

Joined: May 27, 2006
Posts: 25
Do you comment methods of inner classes? Given the atomic nature of my inner classes, I feel redundant having to comment the inner class and its (only) method. Many lines would be added uselessly.


SCJP, SCJD<br />(now studying for SCWCD)
Lucy Hummel
Ranch Hand

Joined: Apr 07, 2005
Posts: 232
Hi Dalton,

Yes, I comment all classes and methods. I do not care if private, protected, public, default methods/classes.
Since I do not have any anonymous classes, I could not decided wheter to comment or not comment them
The one I had I dropped or I put them to inner classes.
Romeo Son
Ranch Hand

Joined: Mar 12, 2007
Posts: 92

Hi Hummel,

I am not yet at JavaDoc step, but I will follow your approach, to avoid any risk, using the -private option in the ant script.

Thanks,

Romeo
Luiz Reginaldo Curado
Ranch Hand

Joined: Jan 19, 2006
Posts: 108
Well, friends... It's done. I submited my assignmnet with the public inner classes.
Lucy Hummel
Ranch Hand

Joined: Apr 07, 2005
Posts: 232
Great,
I am going to follow hopefully quite soon.

When are you going to the exam?
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Listener classes + javadoc
 
Similar Threads
Inner class or methods
Question on widening ,boxing
do public ActionListener classes/actionPerformed() methods need Javadocs?
Regular expressions in Java
servlet context and servlet config