Listener classes + javadoc

[Luiz Reginaldo Curado]

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]

Hi,

I comment them.

[Luiz Reginaldo Curado]

Hi, Hummel.

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

[Romeo Son]

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 ]

[Luiz Reginaldo Curado]

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]

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]

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, coderanch, 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]

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]

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.

[Lucy Hummel]

Hi Dalton,

Yes, I comment all classes and methods. I do not care if private, protected, coderanch, 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]

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]

Well, friends... It's done. I submited my assignmnet with the public inner classes.

[Lucy Hummel]

Great,
I am going to follow hopefully quite soon.

When are you going to the exam?