Javadoc rethinking?

Discussion in 'Java' started by bob smith, Jan 16, 2013.

  1. bob smith

    bob smith Guest

    Am I the only one who thinks that maybe there ought to be some improvementsto the Javadoc process?

    I was just looking at a Javadoc for a DatePickerDialog, and it seemed like it was missing something… that something was an image of an example of the dialog. I think that would have been very helpful.

    However, Javadocs don't support images, and it is not necessarily good for the crucial documentation to be mingled with the code.

    Does anyone else think the Javadoc idea could perhaps use some rethinking?
    bob smith, Jan 16, 2013
    #1
    1. Advertising

  2. bob smith

    Arne Vajhøj Guest

    On 1/16/2013 10:38 AM, bob smith wrote:
    > Am I the only one who thinks that maybe there ought to be some
    > improvements to the Javadoc process?
    >
    > I was just looking at a Javadoc for a DatePickerDialog, and it seemed
    > like it was missing something… that something was an image of an
    > example of the dialog. I think that would have been very helpful.
    >
    > However, Javadocs don't support images, and it is not necessarily
    > good for the crucial documentation to be mingled with the code.


    JavaDoc support HTML tags and I would assume they support IMG tag??

    Arne
    Arne Vajhøj, Jan 16, 2013
    #2
    1. Advertising

  3. bob smith

    Stefan Ram Guest

    bob smith <> writes:
    >However, Javadocs don't support images,


    Writing an image of a DatePickerDialog in a JavaDoc-
    compatible way only did cost me about 7 minutes.

    ..--------------------------------------.
    | -- |
    | |\_| perjantaina 10, kesäkuuta |
    | '__' 2011 |
    | |
    | .-------. .-------. .-------. |
    | | + | | + | | + | |
    | |-------| |-------| |-------| |
    | | 10 | |kuuta | | 2011 | |
    | |-------| |-------| |-------| |
    | | - | | - | | - | |
    | '-------' '-------' '-------' |
    | |
    |--------------------------------------|
    | .--------------. .----------------. |
    | | Aseta | | Peruuta | |
    | '--------------' '----------------' |
    '--------------------------------------'

    One could even imagine an implementation of Swing for text
    terminals, where the DatePickerDialog would look like that
    literally.

    (I do not know the language of the dialog as used above.)
    Stefan Ram, Jan 16, 2013
    #3
  4. On 16/01/13 15:38, bob smith wrote:
    > However, Javadocs don't support images, and it is not necessarily good for the crucial documentation to be mingled with the code.


    <http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#unprocessed>

    --
    ss at comp dot lancs dot ac dot uk
    Steven Simpson, Jan 16, 2013
    #4
  5. -berlin.de (Stefan Ram) writes:
    > bob smith <> writes:
    >>However, Javadocs don't support images,


    > Writing an image of a DatePickerDialog in a JavaDoc-
    > compatible way only did cost me about 7 minutes.
    > .--------------------------------------.
    > | -- |
    > | |\_| perjantaina 10, kesäkuuta |
    > | '__' 2011 |


    > (I do not know the language of the dialog as used above.)


    It's Finnish. (Friday, 10th of June)
    Funny that you happened to use it without even recognizing the language.

    --
    Jukka Lahtinen
    Jukka Lahtinen, Jan 16, 2013
    #5
  6. bob smith

    Lew Guest

    Lew, Jan 17, 2013
    #6
  7. In article <148.btinternet.com>,
    Steven Simpson <> wrote:

    > On 16/01/13 15:38, bob smith wrote:
    > > However, Javadocs don't support images, and it is not necessarily
    > > good for the crucial documentation to be mingled with the code.

    >

    <http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#unprocessed>

    As a concrete example, the images accompanying GridLayout

    <http://docs.oracle.com/javase/7/docs/api/java/awt/GridLayout.html>

    may be found among the doc-files of the awt package:

    $ ls -1 java/awt/doc-files/GridLayout-*
    java/awt/doc-files/GridLayout-1.gif
    java/awt/doc-files/GridLayout-2.gif

    --
    John B. Matthews
    trashgod at gmail dot com
    <http://sites.google.com/site/drjohnbmatthews>
    John B. Matthews, Jan 17, 2013
    #7
  8. bob smith

    Roedy Green Guest

    On Wed, 16 Jan 2013 07:38:18 -0800 (PST), bob smith
    <> wrote, quoted or indirectly quoted someone
    who said :

    >
    >I was just looking at a Javadoc for a DatePickerDialog, and it seemed like =
    >it was missing something=85 that something was an image of an example of t=
    >he dialog. I think that would have been very helpful.


    AMEN! I have often wanted to illustrate layouts too.

    Another feature I would like is commentary on @see to explain why that
    other reference might be germane. Or how it differs from this method.

    If you start inserting entities, the Javadoc quickly becomes
    unreadable to the programmer. The IDE should render it or there should
    be some way to write it without entities. Perhaps we should presume
    UTF-8 for all Java source.
    --
    Roedy Green Canadian Mind Products http://mindprod.com
    The first 90% of the code accounts for the first 90% of the development time.
    The remaining 10% of the code accounts for the other 90% of the development
    time.
    ~ Tom Cargill Ninety-ninety Law
    Roedy Green, Jan 17, 2013
    #8
    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. Magnus Lycka

    Rethinking the Python tutorial

    Magnus Lycka, Feb 9, 2006, in forum: Python
    Replies:
    11
    Views:
    526
    Magnus Lycka
    Feb 15, 2006
  2. stork
    Replies:
    6
    Views:
    341
    Michael Ashton
    Dec 18, 2006
  3. dorayme
    Replies:
    0
    Views:
    370
    dorayme
    May 4, 2008
  4. Steven D'Aprano
    Replies:
    138
    Views:
    1,931
  5. James Edward Gray II

    Rethinking Memoization

    James Edward Gray II, Jan 24, 2006, in forum: Ruby
    Replies:
    8
    Views:
    146
    Robert Klemme
    Jan 27, 2006
Loading...

Share This Page