Re: Toward better Javadoc

Discussion in 'Java' started by Lew, May 1, 2009.

  1. Lew

    Lew Guest

    Roedy Green wrote:
    > Something has always disgusted me about Javadoc -- that you are
    > supposed to embed unreadable HTML in your program comments.


    You are supposed to embed HTML in Javadoc comments, sometimes. No one
    requires that it be unreadable.

    > This makes them often unusable for those who need them most.


    Only if you do it wrong.

    > I have done quite a bit of thinking about the problem, and I have
    > composed list of the Javadoc negatives and suggested solutions. It
    > requires the expressive power of HTML to explain.


    Isn't that ironic?

    > See
    > http://mindprod.com/jgloss/javadoc.html#YUCH


    To display
    > mínus tólf þúsund og þrjú hundruð fjörutíu og fimm


    I embedded in a test class 'Generitor' the comment:

    /** Generitor.
    * mínus tólf þúsund og þrjú hundruð fjörutíu og fimm
    */

    and got in the generated HTML, as viewed in Firefox or Konqueror:

    Generitor. mínus tólf þúsund og þrjú hundruð fjörutíu og fimm

    So the answer to your question:
    > Would it not be so much nicer if could be coded ... in plain text Unicode[?]


    is, it can!

    Did you actually try this yourself before writing your complaint?

    > If the encoding of the generated HTML is embedded as utf-8,
    > then there is no need for accented character entities in
    > the generated HTML. There is no need for entities either in
    > the Javadoc. You could encode awkward characters in your in
    > your comments with or without entities.


    That's how it works now, with the exception of '&', '<' and '>'.

    > It uses old-style upper-case tags.


    I've only ever used lower-case tags in Javadoc comments. Not once have I used
    upper-case tags.

    > Define a canonical format for Javadoc comments and have
    > IDEs reformat as a matter of course when source code is tidied.
    > This would include collapsing multiple blank lines to one,
    > aligning the stars etc.


    NetBeans and, IIRC, Eclipse do this. Doesn't your IDE?

    > Teach IDEs the conventions so they
    > warn you right away of malformed HTML in Javadoc comments,


    NetBeans and, IIRC, Eclipse do this. Doesn't your IDE?

    > and [have] Javac [sic] treat... them as warnings.


    The point of Javadoc comments is that they are *comments* and not covered by
    'javac'. IOW, fundamentally they are intended to be ignored by 'javac'.
    Perhaps you meant have 'javadoc' treat them as warnings?

    > For a Javadoc comment without embedded HTML tags,
    > treat them [sic] as if they had been enclosed in <pre> … </pre>


    That would break a lot of existing Javadoc comments and be a fundamental
    change. Personally I prefer the way it's done now.

    --
    Lew
     
    Lew, May 1, 2009
    #1
    1. Advertising

  2. Lew wrote:
    >
    > The point of Javadoc comments is that they are *comments* and not
    > covered by 'javac'.


    Except for @deprecated, of course. Though now that the @Deprecated
    annotation is available, I think the use of @deprecated should be, well, you
    know.
     
    Mike Schilling, May 1, 2009
    #2
    1. Advertising

  3. Lew

    Lew Guest

    On May 1, 4:22 pm, "Mike Schilling" <>
    wrote:
    > Lew wrote:
    >
    > > The point of Javadoc comments is that they are *comments* and not
    > > covered by 'javac'.

    >
    > Except for @deprecated, of course.  Though now that the @Deprecated
    > annotation is available, I think the use of @deprecated should be, well, you
    > know.


    Naturally, there's documentation on this matter at java.sun.com.
    <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    deprecation/deprecation.html>
    > Starting with J2SE 5.0, you deprecate a class, method, or field
    > by using the @Deprecated annotation. Additionally, you can use
    > the @deprecated Javadoc tag tell developers what to use instead.

    ....
    <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    deprecation/deprecation.html#javadoc_tag>
    > The following examples show how to use the @deprecated Javadoc tag.
    > They also illustrate the @Deprecated annotation, to emphasize that
    > the two should be used together.

    ....
    > * @deprecated As of release 1.3, replaced by {@link #getPreferredSize()}


    So, no, the "@deprecated" tag is not deprecated itself. It is a
    valuable part of the documentation for what to do with deprecated
    constructs.

    I learn so much when I RTFM!

    --
    Lew
     
    Lew, May 1, 2009
    #3
  4. Lew

    Eric Sosman Guest

    Lew wrote:
    > On May 1, 4:22 pm, "Mike Schilling" <>
    > wrote:
    >> Lew wrote:
    >>
    >>> The point of Javadoc comments is that they are *comments* and not
    >>> covered by 'javac'.

    >> Except for @deprecated, of course. Though now that the @Deprecated
    >> annotation is available, I think the use of @deprecated should be, well, you
    >> know.

    >
    > Naturally, there's documentation on this matter at java.sun.com.
    > <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    > deprecation/deprecation.html>
    >> Starting with J2SE 5.0, you deprecate a class, method, or field
    >> by using the @Deprecated annotation. Additionally, you can use
    >> the @deprecated Javadoc tag tell developers what to use instead.

    > ...
    > <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    > deprecation/deprecation.html#javadoc_tag>
    >> The following examples show how to use the @deprecated Javadoc tag.
    >> They also illustrate the @Deprecated annotation, to emphasize that
    >> the two should be used together.

    > ...
    >> * @deprecated As of release 1.3, replaced by {@link #getPreferredSize()}

    >
    > So, no, the "@deprecated" tag is not deprecated itself. It is a
    > valuable part of the documentation for what to do with deprecated
    > constructs.
    >
    > I learn so much when I RTFM!


    "Believe ten percent of what you hear, fifty percent of
    what you read, and ninety percent of what you see for yourself."

    By actual experiment with javac 1.6.0_13, the @deprecated
    tag on a method elicits deprecation warnings when the tagged
    method is used elsewhere. (So, too, does the @Deprecated
    annotation -- but @deprecated remains "significant" and not
    merely a comment.)

    ... and I'm ninety percent sure of that.

    --
    Eric Sosman
    lid
     
    Eric Sosman, May 1, 2009
    #4
  5. Lew

    Lew Guest

    Eric Sosman wrote:
    > Lew wrote:
    >> On May 1, 4:22 pm, "Mike Schilling" <>
    >> wrote:
    >>> Lew wrote:
    >>>
    >>>> The point of Javadoc comments is that they are *comments* and not
    >>>> covered by 'javac'.
    >>> Except for @deprecated, of course. Though now that the @Deprecated
    >>> annotation is available, I think the use of @deprecated should be,
    >>> well, you
    >>> know.

    >>
    >> Naturally, there's documentation on this matter at java.sun.com.
    >> <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    >> deprecation/deprecation.html>
    >>> Starting with J2SE 5.0, you deprecate a class, method, or field
    >>> by using the @Deprecated annotation. Additionally, you can use
    >>> the @deprecated Javadoc tag tell developers what to use instead.

    >> ...
    >> <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    >> deprecation/deprecation.html#javadoc_tag>
    >>> The following examples show how to use the @deprecated Javadoc tag.
    >>> They also illustrate the @Deprecated annotation, to emphasize that
    >>> the two should be used together.

    >> ...
    >>> * @deprecated As of release 1.3, replaced by {@link
    >>> #getPreferredSize()}

    >>
    >> So, no, the "@deprecated" tag is not deprecated itself. It is a
    >> valuable part of the documentation for what to do with deprecated
    >> constructs.
    >>
    >> I learn so much when I RTFM!

    >
    > "Believe ten percent of what you hear, fifty percent of
    > what you read, and ninety percent of what you see for yourself."
    >
    > By actual experiment with javac 1.6.0_13, the @deprecated
    > tag on a method elicits deprecation warnings when the tagged
    > method is used elsewhere. (So, too, does the @Deprecated
    > annotation -- but @deprecated remains "significant" and not
    > merely a comment.)
    >
    > ... and I'm ninety percent sure of that.


    More evidence that it isn't deprecated itself.

    --
    Lew


    --
    Lew
     
    Lew, May 2, 2009
    #5
  6. Lew

    charlesbos73 Guest

    On May 1, 2:28 pm, Lew <> wrote:
    > Roedy Green wrote:
    > > Something has always disgusted me about Javadoc -- that you are
    > > supposed to embed unreadable HTML in your program comments.

    >
    > You are supposed to embed HTML in Javadoc comments, sometimes. No one
    > requires that it be unreadable.
    >
    > > This makes them often unusable for those who need them most.

    >
    > Only if you do it wrong.


    How do you provide a correct, easy to read, javadoc
    containing '<', '>' or '&' ?

    As a programmer, you see, I tend to use '<', '>' and
    '&' and I tend to need to be able to refer to them
    from the Javadocs from time to time.


    > Did you actually try this yourself before writing your complaint?


    The rudeness in the way you formulated that question
    to Roedy is neither necessary nor appreciated.

    Now if you *think* that wasn't a rudely formulated
    question, a good question would be why I took it
    as rude. But that's a question you'll have to ask
    to yourself.


    > That's how it works now, with the exception of '&', '<' and '>'.


    Oh... Here we go.

    So Roedy's "written complaint" [sic] was maybe valid after all?

    Roedy's problem can be solved, at least at the IDE
    level, by using an IDE that supports code folding.
    Your IDE shows you '&' even tough it's really "&amp;"
    that is present in your source file.

    IntelliJ IDEA supports code folding, it does it
    automatically for plain getters/setters for example.
    The autofolded parts are using a special color code
    so that you know you're seeing an folded part
    of your .java file.

    There are also several code-folding facilities
    available for Emacs and vi, for some very smart people
    have been fed up by unnecessarily unreadable
    garbage polluting their screen (I've used
    auto-folding in Emacs when editing extremely
    verbose LaTeX files, for example).

    Writing your own IntelliJ IDEA plugin that would
    fold to '&', '<' and '>' is probably trivial seen
    of clean their plugin API is and seen that they
    already support code-folding.


    > Personally I prefer the way it's done now.


    Personally I'd prefer to have a code-folding plugin
    for my IDE taking care of this issue because I think
    Roedy has a perfectly valid point.

    YMMV.
     
    charlesbos73, May 2, 2009
    #6
  7. Lew

    Eric Sosman Guest

    Lew wrote:
    > Eric Sosman wrote:
    >> Lew wrote:
    >>> On May 1, 4:22 pm, "Mike Schilling" <>
    >>> wrote:
    >>>> Lew wrote:
    >>>>
    >>>>> The point of Javadoc comments is that they are *comments* and not
    >>>>> covered by 'javac'.
    >>>> Except for @deprecated, of course. Though now that the @Deprecated
    >>>> annotation is available, I think the use of @deprecated should be,
    >>>> well, you
    >>>> know.
    >>>
    >>> Naturally, there's documentation on this matter at java.sun.com.
    >>> <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    >>> deprecation/deprecation.html>
    >>>> Starting with J2SE 5.0, you deprecate a class, method, or field
    >>>> by using the @Deprecated annotation. Additionally, you can use
    >>>> the @deprecated Javadoc tag tell developers what to use instead.
    >>> ...
    >>> <http://java.sun.com/javase/6/docs/technotes/guides/javadoc/
    >>> deprecation/deprecation.html#javadoc_tag>
    >>>> The following examples show how to use the @deprecated Javadoc tag.
    >>>> They also illustrate the @Deprecated annotation, to emphasize that
    >>>> the two should be used together.
    >>> ...
    >>>> * @deprecated As of release 1.3, replaced by {@link
    >>>> #getPreferredSize()}
    >>>
    >>> So, no, the "@deprecated" tag is not deprecated itself. It is a
    >>> valuable part of the documentation for what to do with deprecated
    >>> constructs.
    >>>
    >>> I learn so much when I RTFM!

    >>
    >> "Believe ten percent of what you hear, fifty percent of
    >> what you read, and ninety percent of what you see for yourself."
    >>
    >> By actual experiment with javac 1.6.0_13, the @deprecated
    >> tag on a method elicits deprecation warnings when the tagged
    >> method is used elsewhere. (So, too, does the @Deprecated
    >> annotation -- but @deprecated remains "significant" and not
    >> merely a comment.)
    >>
    >> ... and I'm ninety percent sure of that.

    >
    > More evidence that it isn't deprecated itself.


    Perhaps I misunderstood what you meant by

    >>> So, no, the "@deprecated" tag is not deprecated itself.


    I thought you were saying that the @deprecated tag is not
    That Which Deprecates, having been superseded by the @Deprecated
    annotation. C.f. "We have nothing to fear but fear itself."

    ... but perhaps you were saying that nobody deprecates
    the use of the @deprecated tag, even though the @Deprecated
    annotation now exists as an alternative, possibly preferred?

    --
    Eric Sosman
    lid
     
    Eric Sosman, May 2, 2009
    #7
  8. In article
    <>,
    charlesbos73 <> wrote:

    > On May 1, 2:28 pm, Lew <> wrote:
    > > Roedy Green wrote:
    > > > Something has always disgusted me about Javadoc -- that you are
    > > > supposed to embed unreadable HTML in your program comments.

    > >
    > > You are supposed to embed HTML in Javadoc comments, sometimes. No
    > > one requires that it be unreadable.
    > >
    > > > This makes them often unusable for those who need them most.

    > >
    > > Only if you do it wrong.

    >
    > How do you provide a correct, easy to read, javadoc
    > containing '<', '>' or '&' ?


    /**
    * <code>Testing: <i>in progress</i></code>.
    * Clearly, 2 + 2 < 4 for small values of 2 & large values of 4.
    */

    I'm having trouble seeing a problem. I notice NetBeans' Print to HTML
    conveniently escapes the relevant symbols.

    > As a programmer, you see, I tend to use '<', '>' and
    > '&' and I tend to need to be able to refer to them
    > from the Javadocs from time to time.
    >
    > > Did you actually try this yourself before writing your complaint?


    I tried it using several tools, including NetBeans 6.5.1, vi 7.2.22, my
    favorite text editor, and assorted platform-dependent tools.

    > The rudeness in the way you formulated that question
    > to Roedy is neither necessary nor appreciated.
    >
    > Now if you *think* that wasn't a rudely formulated
    > question, a good question would be why I took it
    > as rude. But that's a question you'll have to ask
    > to yourself.


    How could someone else know how you arrived at a particular perception?

    As an aside, I might have taken umbrage had I felt I was being unfairly
    called lazy, but I _am_ lazy. I devote considerable effort to it!

    > > That's how it works now, with the exception of '&', '<' and '>'.

    >
    > Oh... Here we go.
    >
    > So Roedy's "written complaint" [sic] was maybe valid after all?
    >
    > Roedy's problem can be solved, at least at the IDE
    > level, by using an IDE that supports code folding.
    > Your IDE shows you '&' even tough it's really "&amp;"
    > that is present in your source file.


    I can't reproduce this. A hex dump shows me the expected code for each
    of the several encodings I tried. Is this IDE dependent?

    [...]

    --
    John B. Matthews
    trashgod at gmail dot com
    <http://sites.google.com/site/drjohnbmatthews>
     
    John B. Matthews, May 2, 2009
    #8
  9. Lew

    Lew Guest

    Lew wrote:
    >> More evidence that it isn't deprecated itself.


    Eric Sosman wrote:
    > Perhaps I misunderstood what you meant by
    >
    > >>> So, no, the "@deprecated" tag is not deprecated itself.


    Apparently.

    > I thought you were saying that the @deprecated tag is not
    > That Which Deprecates, having been superseded by the @Deprecated
    > annotation. C.f. "We have nothing to fear but fear itself."


    No, I was saying that use of the "@deprecated" Javadoc tag is not deprecated
    itself.

    > ... but perhaps you were saying that nobody deprecates
    > the use of the @deprecated tag, even though the @Deprecated
    > annotation now exists as an alternative, possibly preferred?


    That isn't really what I'm saying either, though it's closer.

    The "@Deprecated" annotation is neither an alternative nor preferred. Looking
    at the Sun documentation for the Javadoc "@deprecated" tag that I cited
    upthread, it is crystal clear that the tag is not deprecated, and that the
    annotation is not preferred but complementary to it.

    All I was doing was parroting the Sun documentation.

    --
    Lew
     
    Lew, May 2, 2009
    #9
  10. Lew

    Lew Guest

    Lew wrote:
    >> Did you actually try this yourself before writing your complaint?


    charlesbos73 wrote:
    > The rudeness in the way you formulated that question
    > to Roedy is neither necessary nor appreciated.
    >
    > Now if you *think* that wasn't a rudely formulated
    > question, a good question would be why I took it
    > as rude. But that's a question you'll have to ask
    > to yourself.


    It wasn't rude. It was an objective question. If you can't stand the heat,
    stay out of the kitchen.

    I know that Roedy is a rigorous thinker with a strong commitment to providing
    accurate information. In particular, he strives to provide accurate useful
    information to help Java programmers.

    He made patently incorrect statements on his website about the use of Javadoc
    comments, based on what I actually tried. It's fair advice to suggest that he
    test his assumptions, and a fair question to ask if he did. It is possible
    that he did try the things he discussed, and that they operated differently
    for him, perhaps due to environmental differences. The only way to know the
    answer to that is to ask.

    This is a technical forum. Leave your petty antagonistic interpretations at
    the door and stick with the objective matters.

    --
    Lew
     
    Lew, May 2, 2009
    #10
  11. Lew

    Roedy Green Guest

    On Sat, 2 May 2009 04:45:38 -0700 (PDT), charlesbos73
    <> wrote, quoted or indirectly quoted someone who
    said :

    >
    >> Did you actually try this yourself before writing your complaint?


    >
    >The rudeness in the way you formulated that question
    >to Roedy is neither necessary nor appreciated.



    My style of posting irritates some people. They think of the newsgroup
    as a sort of precious resource helpdesk staffed by terribly overworked
    and rare genius. People are supposed ask questions only when
    absolutely stuck. The answers are supposed to be custom tailored to
    the questioner. The responder must not tell questioner what he
    already knows. They must not tell him anything not immediately
    relevant to his particular question.

    I have a quite different approach, based to leading Q&A sessions for
    many years at the Apple and later PC user groups. Someone would ask a
    question. It would be RUDE if my answer were relevant to only him.

    I take the question as a jumping off point to a discussion with
    background for people of all levels, of the problem and related
    problems. I am most definitely NOT talking to the questioner. I am
    talking and trying to entertain the other 100+ people listening. I
    trying to engage EVERYONE to play along and contribute their practical
    experience, particularly how they would like things to work in future.

    When I ask a question myself, I am not purely soliciting information.
    For that, I google or read manuals. I am inviting people to think
    about some interesting topic. I am hoping to get some discussion
    going. Some people don't understand what I am up to and tell me to go
    google and keep my findings to myself, chastising me with
    condescension for wasting their esteemed time reading my question.

    I could do an Xah Lee, but I prefer to get people to consider some
    topic by asking some questions, rhetorical questions and philosophical
    questions.

    Were this the alt.religion conference and I asked "Do you think
    intelligent life elsewhere in the universe would have religions
    anything like ours?" I could imagine some folk here trying to shut me
    by saying "try google", completely missing my intent.

    --
    Roedy Green Canadian Mind Products
    http://mindprod.com

    "Species evolve exactly as if they were adapting as best they could to a changing world, and not at all as if they were moving toward a set goal."
    ~ George Gaylord Simpson
     
    Roedy Green, May 5, 2009
    #11
  12. Lew

    Roedy Green Guest

    On Sat, 2 May 2009 04:45:38 -0700 (PDT), charlesbos73
    <> wrote, quoted or indirectly quoted someone who
    said :

    >
    >> Did you actually try this yourself before writing your complaint?


    >
    >The rudeness in the way you formulated that question
    >to Roedy is neither necessary nor appreciated.



    My style of posting irritates some people. They think of the newsgroup
    as a sort of precious resource helpdesk staffed by terribly overworked
    and rare genius. People are supposed ask questions only when
    absolutely stuck. The answers are supposed to be custom tailored to
    the questioner. The responder must not tell questioner what he
    already knows. They must not tell him anything not immediately
    relevant to his particular question. If anyone does mention something
    about the problem area in general, that does not apply to this
    specific case, it your duty to chastise him for his lack of
    consideration, inability to read and/or comprehend.

    I have a quite different approach, based to leading Q&A sessions for
    many years at the Apple and later PC user groups. Someone would ask a
    question. It would be RUDE if my answer were relevant to only him.

    I take the question as a jumping off point to a discussion with
    background for people of all levels, of the problem and related
    problems. I am most definitely NOT talking to the questioner. I am
    talking and trying to entertain the other 100+ people listening. I
    trying to engage EVERYONE to play along and contribute their practical
    experience, particularly how they would like things to work in future.

    My goal is to increase the competency of EVERYONE present in this
    area. This requires saying a odd mixture of statements interleaved
    aimed at different levels of expertise. Throwing in some humour or
    eccentricity keeps people amused even when the content is still over
    their heads.

    When I ask a question myself, I am not purely soliciting information.
    For that, I google or read manuals. I am inviting people to think
    about some interesting topic. I am hoping to get some discussion
    going. Some people don't understand what I am up to and tell me to go
    google and keep my findings to myself, chastising me with
    condescension for wasting their esteemed time reading my question.

    I could do an Xah Lee, but I prefer to get people to consider some
    topic by asking some questions, rhetorical questions and philosophical
    questions.

    Were this the alt.religion conference and I asked "Do you think
    intelligent life elsewhere in the universe would have religions
    anything like ours?" I could imagine some folk here trying to shut me
    by saying "try google", completely missing my intent.

    --
    Roedy Green Canadian Mind Products
    http://mindprod.com

    "Species evolve exactly as if they were adapting as best they could to a changing world, and not at all as if they were moving toward a set goal."
    ~ George Gaylord Simpson
     
    Roedy Green, May 5, 2009
    #12
  13. Roedy Green wrote:
    > My style of posting irritates some people. They think of the newsgroup
    > as a sort of precious resource helpdesk staffed by terribly overworked
    > and rare genius. People are supposed ask questions only when
    > absolutely stuck. The answers are supposed to be custom tailored to
    > the questioner. The responder must not tell questioner what he
    > already knows. They must not tell him anything not immediately
    > relevant to his particular question.


    And then there are people who find your posts irritatingly self-righteous.
    Go figure.
     
    Mike Schilling, May 8, 2009
    #13
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Frankie

    OT: Toward WYSIWYG Web Page Authoring

    Frankie, Oct 2, 2005, in forum: ASP .Net
    Replies:
    4
    Views:
    419
    Mr Newbie
    Oct 2, 2005
  2. Replies:
    0
    Views:
    351
  3. Replies:
    1
    Views:
    337
    Mats Lycken
    Mar 9, 2006
  4. Roedy Green

    Toward more efficient ArrayLists

    Roedy Green, Jun 28, 2003, in forum: Java
    Replies:
    10
    Views:
    1,515
    Jon Skeet
    Jul 3, 2003
  5. Trans
    Replies:
    0
    Views:
    81
    Trans
    Aug 13, 2006
Loading...

Share This Page