JavaDocs in the other direction

Discussion in 'Java' started by Joona I Palaste, Dec 30, 2003.

  1. JavaDocs, as we know them, describe what a method does, to help people
    who are calling it from outside code.
    But what if we need documentation in the other direction - to help
    people who are trying to implement the method? They may need
    documentation about when and where the method is going to get called,
    and with what parameters, and how its return value will be used.
    In short, what the method expects, and what it assures.
    For example, this sort of "JavaDoc" might be necessary:

    /**
    * Should create a shallow clone of the array.
    * @param arr: This is the array. It will already have been sorted
    * according to the natural order, so don't worry about using
    * optimised algorithms. Also, all references will be non-null.
    * @return Another array. This array is a shallow copy of the
    * original. No one is ever going to modify this array, but the
    * original might get modified. Think of this as a "backup array" to
    * see what the original array "originally" looked like.
    */
    public Comparable[] cloneArray(Comparable[] arr);

    Are there such JavaDocs defined? Does anyone use them? Would there be
    any real benefit from them?

    --
    /-- Joona Palaste () ------------- Finland --------\
    \-- http://www.helsinki.fi/~palaste --------------------- rules! --------/
    "How can we possibly use sex to get what we want? Sex IS what we want."
    - Dr. Frasier Crane
    Joona I Palaste, Dec 30, 2003
    #1
    1. Advertising

  2. Joona I Palaste wrote:

    > JavaDocs, as we know them, describe what a method does, to help people
    > who are calling it from outside code.
    > But what if we need documentation in the other direction - to help
    > people who are trying to implement the method? They may need
    > documentation about when and where the method is going to get called,
    > and with what parameters, and how its return value will be used.


    I don't see the difference. The information in the comment you give as an
    example is *at least* as important to the users of the API as to the
    implementor. The only difference is in the wording: to the implementor
    the parameter array "will already have been sorted", to the caller
    it *must* be sorted before calling the method.
    Michael Borgwardt, Dec 30, 2003
    #2
    1. Advertising

  3. "Joona I Palaste" <> wrote in message
    news:bssdv8$qv6$...
    > JavaDocs, as we know them, describe what a method does, to help people
    > who are calling it from outside code.
    > But what if we need documentation in the other direction - to help
    > people who are trying to implement the method? They may need
    > documentation about when and where the method is going to get called,
    > and with what parameters, and how its return value will be used.
    > In short, what the method expects, and what it assures.
    > For example, this sort of "JavaDoc" might be necessary:
    >
    > /**
    > * Should create a shallow clone of the array.
    > * @param arr: This is the array. It will already have been sorted
    > * according to the natural order, so don't worry about using
    > * optimised algorithms. Also, all references will be non-null.
    > * @return Another array. This array is a shallow copy of the
    > * original. No one is ever going to modify this array, but the
    > * original might get modified. Think of this as a "backup array" to
    > * see what the original array "originally" looked like.
    > */
    > public Comparable[] cloneArray(Comparable[] arr);
    >
    > Are there such JavaDocs defined? Does anyone use them? Would there be
    > any real benefit from them?


    well, when writing code it is a common practice to create pseudo code from
    the requirements or design documentation when you start actual coding. if
    you are thinking ahead you format comments so that tools like javadoc can
    extract them and create the actual software design documentation for review
    before implementation. this saves having to write a separate document
    before starting on roughing in the code. if you are really doing it the
    smart way the pseudo code is compilable and can be used to check
    compatibility of interfaces before finishing the design. there are lots of
    books and tools available that talk about the software design process and
    how to automate it to speed development and reduce errors.
    David Robbins, Dec 30, 2003
    #3
  4. Joona I Palaste

    Adam Jenkins Guest

    Joona I Palaste wrote:
    > JavaDocs, as we know them, describe what a method does, to help people
    > who are calling it from outside code.
    > But what if we need documentation in the other direction - to help
    > people who are trying to implement the method? They may need
    > documentation about when and where the method is going to get called,
    > and with what parameters, and how its return value will be used.
    > In short, what the method expects, and what it assures.

    ....
    > Are there such JavaDocs defined? Does anyone use them? Would there be
    > any real benefit from them?


    Sure, look at the documentation for any interface. The Javadocs for the
    standard Java libraries are full of examples. For example, look at the
    documentation for java.util.{Collection,Map,List}. They're exactly the
    kind of documentation you're talking about. They define how
    implementations of these interfaces are expected to behave. Some more
    examples from the standard libraries:

    - org.w3c.dom.*
    - org.xml.sax.*
    - most of java.sql.*

    I'm not sure what you think is different about these from the example
    you're giving.
    Adam Jenkins, Dec 30, 2003
    #4
    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. ashish

    javadocs equivalent for .net

    ashish, Apr 15, 2004, in forum: ASP .Net
    Replies:
    2
    Views:
    609
    Maxim Kazitov
    Apr 16, 2004
  2. Dan W
    Replies:
    2
    Views:
    311
    Carlton S. Anderson
    Jul 15, 2003
  3. Ahmed Moustafa
    Replies:
    3
    Views:
    365
    Ahmed Moustafa
    Sep 5, 2003
  4. Torsten Nahm
    Replies:
    0
    Views:
    430
    Torsten Nahm
    Nov 7, 2003
  5. Leonard Slatkin
    Replies:
    1
    Views:
    4,427
    Ray Tayek
    Nov 30, 2003
Loading...

Share This Page