Do people use JavaDoc-style comments?

Hello everyone,

C# has a relatively little-known feature - support for JavaDoc-style XML doc comments (starting with /**), in addition to regular doc comments (starting with /// in each line). Personally, I find the standard comments very poorly readable, because of a huge mass of / and < and >, and the JavaDoc comments look much nicer. I've been asking Resharper developers to add a feature for generating the JavaDoc comments (similar to what Visual Studio does when you type ///), and they asked me to get some support for my request in the newsgroup.

Does anyone actually use JavaDoc-style comments? Do you like them better than the standard C# comments or not?

--
Dmitry Jemerov
OmniaMea Project Leader
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"

7 comments
Comment actions Permalink

Hello Dmitry,

I find to me the main benefits of the XMLDoc comments is that they can be auto-generated into documentation and show up in intellisense. If the JavaDoc styles comments are not able to help me with either, the readability is not enough to get me to use them. Just my $.02.

-Michael

Hello everyone,

C# has a relatively little-known feature - support for JavaDoc-style
XML doc comments (starting with /**), in addition to regular doc
comments (starting with /// in each line). Personally, I find the
standard comments very poorly readable, because of a huge mass of /
and < and >, and the JavaDoc comments look much nicer. I've been
asking Resharper developers to add a feature for generating the
JavaDoc comments (similar to what Visual Studio does when you type
///), and they asked me to get some support for my request in the
newsgroup.

Does anyone actually use JavaDoc-style comments? Do you like them
better than the standard C# comments or not?


0
Comment actions Permalink

I also find the XML comments unreadable and can't bear to see them. We use Natural Docs (http://www.naturaldocs.org) and it's great. You can read the comments in the code really well and it produces superb documentation too. However, you do not get anything in the tool tips though!

I have never used Javadoc, but if its like Natural Docs I would be happy to use it.

0
Comment actions Permalink

Hello sean,

sk> I also find the XML comments unreadable and can't bear to see them.
sk> We use Natural Docs (http://www.naturaldocs.org) and it's great.
sk> You can read the comments in the code really well and it produces
sk> superb documentation too. However, you do not get anything in the
sk> tool tips though!
sk>
sk> I have never used Javadoc, but if its like Natural Docs I would be
sk> happy to use it.

Thanks for an interesting link! I have looked at NaturalDocs, and it really reads well, but I've found it a bit too verbose for my taste. I still like Java's JavaDoc better because it's more compact and still quite readable (if you don't put too much HTML formatting in it).

Just for the reference, another free documentation tool with limited support for C# is Doxygen (http://www.doxygen.org).


--
Dmitry Jemerov
OmniaMea Project Leader
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"

0
Comment actions Permalink

Thanks Dmitry, I will take a look at that. If Java Doc is less intrusive, I would, of course, use it were it integrated into my refactoring browser :)

0
Comment actions Permalink

I dislike JavaDocs. Personally I think it looks tacky and rather
unprofessional. This is just my opinion though. I've always found the XML
Style to be very nice.

"sean kearon" <no_mail@jetbrains.com> wrote in message
news:6027129.1082979989092.JavaMail.itn@is.intellij.net...

Thanks Dmitry, I will take a look at that. If Java Doc is less intrusive,
I would, of course, use it were it integrated into my refactoring browser
:)



0
Comment actions Permalink

We use NDoc to generate documentation from the regular doc comments. It
seems to work pretty well for us.

Shamir.

"Dmitry Jemerov (JetBrains)" <yole@jetbrains.com> wrote in message
news:c68ue8$114$1@is.intellij.net...

Hello everyone,

>

C

  1. has a relatively little-known feature - support for JavaDoc-style XML

doc comments (starting with /**), in addition to regular doc comments
(starting with /// in each line). Personally, I find the standard comments
very poorly readable, because of a huge mass of / and < and >, and the
JavaDoc comments look much nicer. I've been asking Resharper developers to
add a feature for generating the JavaDoc comments (similar to what Visual
Studio does when you type ///), and they asked me to get some support for my
request in the newsgroup.
>

Does anyone actually use JavaDoc-style comments? Do you like them better

than the standard C# comments or not?
>

--
Dmitry Jemerov
OmniaMea Project Leader
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"



0
Comment actions Permalink

I like javadoc style comments. It's interesting that anyone thinks ///
comments are more readable. However, I don't want to give up the
"intellisense" for doc tags.

When you support code doc tags (NDoc superset me hopes) I'd use javadoc
style comments exclusively.

/jhd

"Dmitry Jemerov (JetBrains)" <yole@jetbrains.com> wrote in message
news:c68ue8$114$1@is.intellij.net...

Hello everyone,

>

C

  1. has a relatively little-known feature - support for JavaDoc-style XML

doc comments (starting with /**), in addition to regular doc comments
(starting with /// in each line). Personally, I find the standard comments
very poorly readable, because of a huge mass of / and < and >, and the
JavaDoc comments look much nicer. I've been asking Resharper developers to
add a feature for generating the JavaDoc comments (similar to what Visual
Studio does when you type ///), and they asked me to get some support for my
request in the newsgroup.
>

Does anyone actually use JavaDoc-style comments? Do you like them better

than the standard C# comments or not?
>

--
Dmitry Jemerov
OmniaMea Project Leader
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"



0

Please sign in to leave a comment.