Java doc comments

[cyber Boy]

Hy,

I have one interesting discussion for writing Java doc comments.
The article about Java code convention you can found on the following link:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#385

Does Java doc comments (/** ... */) the best convention for writing comments
for a private and protected scopes ?

This comments doesn't visible outside of a class and doesn't visible in the
Java API documents.
Maybe the better approach is Block comments (/* .. */).
But changing scopes (public, private, protected) we have to change a style
for writing comments.

What do you think ?

Regards,
cyber1boy

 

[Tom McGlynn]

Hy,

I have one interesting discussion for writing Java doc comments.
The article about Java code convention you can found on the following link:http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#385

Does Java doc comments (/** ... */) the best convention for writing comments
for a private and protected scopes ?

This comments doesn't visible outside of a class and doesn't visible in the
Java API documents.
Maybe the better approach is Block comments (/* .. */).
But changing scopes (public, private, protected) we have to change a style
for writing comments.

What do you think ?

Regards,
cyber1boy

If your concern is that you aren't seeing comments about private and
protected members in the documentation produced by the javadoc
command, perhaps you need to indicate that you want them included.
Adding -private to the javadoc command ensures that documentation for
all members is included in the resulting documentation (with similar -
package, -protected and -public arguments that progressively restrict
the output).
You should be seeing protected members by default though...


Regards,
Tom McGlynn

 

[Martin Gregorie]

Hy,

I have one interesting discussion for writing Java doc comments. The
article about Java code convention you can found on the following link:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#385

Does Java doc comments (/** ... */) the best convention for writing
comments for a private and protected scopes ?

This comments doesn't visible outside of a class and doesn't visible in
the Java API documents.
Maybe the better approach is Block comments (/* .. */). But changing
scopes (public, private, protected) we have to change a style for
writing comments.

I always use the /** .... */ form in front of the method declaration. The
source looks tidier that way. I write all comments to be included in the
Javadoc page before the method is coded since they should describe the
class and methods in an implementation-independent way and doing it this
way tends to help me get the method arguments right. IMO these comments
are more a low-level module spec than anything else.

I write any comments inside a method as
/* .... */ because IMO they shouldn't appear in Javadocs because they are
implementation-specific. Last but not least, they are very difficult to
write so that the Javadoc reads nicely..

 

[Lew]

Hy,

I have one interesting discussion for writing Java doc comments.
The article about Java code convention you can found on the following link:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#385

Does Java doc comments (/** ... */) the best convention for writing comments
for a private and protected scopes ?

It's necessary for protected scope and perfectly suitable for private.

This comments doesn't visible outside of a class and doesn't visible in the
Java API documents.

You are mistaken. Protected scope by design is visible outside the class, and
by default is visible in the generated Javadocs.

Maybe the better approach is Block comments (/* .. */).
Nope.

But changing scopes (public, private, protected) we have to change a style
for writing comments.

Well before you release code for use, you had better have nailed down the
scope of your members. Once you have committed to a visible API (public,
protected), you have promised lifetime support for those members.

If you are increasing scope from private or package-private to protected or
public, why would adding an extra asterisk to your comment be a problem? You
are making a mountain out of a molehill.

However, since there's no problem using Javadoc-style comments for
(package)-private elements, you could just do that and easily leap the
molehill that way.

Except for the misunderstanding of protected as being invisible outside the
class, this whole thing is a non-issue.

 

[Hendrik Maryns]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martin Gregorie schreef:

I always use the /** .... */ form in front of the method declaration. The
source looks tidier that way.

Me too, and additionally, I set up Eclipse so that it gives a warning
for every missing method, field or class comment, even at private level.

H.
- --
Hendrik Maryns
http://tcl.sfs.uni-tuebingen.de/~hendrik/
==================
Ask smart questions, get good answers:
http://www.catb.org/~esr/faqs/smart-questions.html
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.9 (GNU/Linux)
Comment: Using GnuPG with SUSE - http://enigmail.mozdev.org

iEYEARECAAYFAkk5QREACgkQBGFP0CTku6MqRQCeN6b/OWk0cbiyT/pvGIWlpAtr
reYAnj5AsAksWI5YgFw2cJWWuJCu1EyK
=54B4
-----END PGP SIGNATURE-----

 

[cyber Boy]

This comments doesn't visible outside of a class and doesn't visible in

You are mistaken. Protected scope by design is visible outside the class,
and by default is visible in the generated Javadocs.

That's right, protected scope is visible outside the class. But in some Java
API documents I found that protected methods wasn't generated in a
documentation and this is reason for this post.

Nope.

I agree with you but I would like to hear what do you mean about comments.

Well before you release code for use, you had better have nailed down the
scope of your members. Once you have committed to a visible API (public,
protected), you have promised lifetime support for those members.

I just commented what is going on in this situation. Nothing else.

However, since there's no problem using Javadoc-style comments for
(package)-private elements, you could just do that and easily leap the
molehill that way.

Except for the misunderstanding of protected as being invisible outside
the class, this whole thing is a non-issue.

I have not accepted all standards for writing Java docs and I investigate
all possible approachs before.


Regards,
cyber1boy

 

[John B. Matthews]

[...]

But in some Java API documents I found that protected methods wasn't
generated in a documentation and this is reason for this post.

[...]

The visibility is controlled by options provided the javadoc tool. The
default shows only protected and public classes and members, but that
may have been changed in the API you saw:

<http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html>

These setting are also available from ant:

<http://ant.apache.org/manual/CoreTasks/javadoc.html>

 

[Lew]

... in some Java
API documents I found that protected methods wasn't generated in a
documentation and this is reason for this post.

Protected members do appear in the published Javadocs unless you
override the default.

You should be seeing protected members by default though...

The default shows only protected and public classes and members ...

The primary purpose of Javadocs is to provide information for
developers who use the classes. Since users of a class generally have
access to public and protected members, those are the levels that must
be documented. In rare cases they have access to package-private
members, potentially justifying publishing Javadocs at that level.
There is no reason to publish Javadocs for private members, in fact it
is a bad idea to do so.

The advantage of Javadoc-style comments for private and package-
private members is consistency of documentation and readability for
maintainers of the class. They will be reading the source code, not
published docs, but the clean layout and consistent format of Javadoc
comments are a real boon to maintainers.

 

[John B. Matthews]

Lew wrote:
...
...

I agree private member Javadocs should not be published, but that does
not mean they should never be generated. I like Javadocs as a good
overview of classes I am actively editing.

This has been my experience. It's also a convenient way to validate
Javadoc syntax or verify meeting a documentation requirement.

 

[Karl Uppiano]

Lew wrote:
...
...

I agree private member Javadocs should not be published, but that does
not mean they should never be generated. I like Javadocs as a good
overview of classes I am actively editing.

Where I work, we generate private JavaDocs in the nightly builds to assist
with development and code/API reviews, but we only ship the public JavaDocs
for our published APIs.

 

[Roedy Green]

Does Java doc comments (/** ... */) the best convention for writing comments
for a private and protected scopes ?

This comments doesn't visible outside of a class and doesn't visible in the
Java API documents.
Maybe the better approach is Block comments (/* .. */).
But changing scopes (public, private, protected) we have to change a style
for writing comments.

See http://mindprod.com/jgloss/javadoc.html

Javadoc comments have a formal structure
// and /* comments are for everything else.
--
Roedy Green Canadian Mind Products
http://mindprod.com
"Humanity is conducting an unintended, uncontrolled, globally pervasive experiment
whose ultimate consequences could be second only to global nuclear war."
~ Environment Canada (The Canadian equivalent of the EPA on global warming)

 

[Volker Borchert]

I agree private member Javadocs should not be published, but that does
not mean they should never be generated. I like Javadocs as a good
overview of classes I am actively editing.

And they help in understanding code written by coworkers or predecessors,
or even oneself years later, especially with IDEs that provide the javadoc
as a bubble help on mouse over.