Results 1 to 5 of 5

Thread: JavaDoc Tool for Documentation

  1. #1
    Join Date
    Feb 2010
    Posts
    136

    JavaDoc Tool for Documentation

    The JavaDoc tool


    1. The JavaDoc Tool

    1.2. What is JavaDoc:
    Javadoc is primarily a tool developed by Sun Microsystems (the company that created the Java language). But by analogy, it is used to generate the documentation and it is used as a documentation tool. This tool is used to produce a comprehensive documentation of your web code by inspecting the code of Java classes.

    1.3. How to get the JavaDoc tool:
    The Javadoc tool is included in all JDK (or SDK) for Java. To download the latest version of the JDK, visit this link http://java.sun.com/javase/downloads/index.jsp. If you already have a JDK installed on your machine, you can find the Javadoc tool in the bin directory of the file.

    1.4. What exactly does JavaDoc generate:
    The tool generates HTML pages containing at least the list of classes, the list of methods and the list of variables. It is possible to add a lot of information, comments, to generate a true documentation, comprehensive and easily readable. The advantage of the HTML used in the literature is produced in the presence of hyperlinks. It becomes very easy to navigate documentation, over reading.
    Last edited by blueprats; 19-02-2010 at 05:25 AM.

  2. #2
    Join Date
    Feb 2010
    Posts
    136

    Re: JavaDoc Tool for Documentation

    1.5. Some of the examples:
    Here are some of the examples of documentation generated by the JavaDoc tool.








  3. #3
    Join Date
    Feb 2010
    Posts
    136

    Re: JavaDoc Tool for Documentation

    2. JavaDoc Tags

    You can add a lot of information to a code, using comments. But they are not taken into account by the Javadoc tool. But Sun has done some things, there are comments made specially for the Javadoc, and more better, tags that allow precise detailing information about each class, each method, variables etc. As you all know, there are three types of comments in Java. The comments on lines, comments on several lines, and Javadoc comments.

    Here is an example showing the three types of comment

    Code:
    /**
     * This is a Comment for Javadoc. 
     * It begins by a slash followed of two stars. 
     * Each row must then begin by a star. 
     * Finally, it finished by a star followed the slash.
     */
    protected Vector<Zero> getVectorAmis(){
            // This is a Comment on a row
            Vector<Zero> vec = new Vector<Zero>();
            /* This is a Comment on 
            many lines */
            for (Z Zero: list){
                    vec.add(z);
            }
            return vec;
    }
    So all the information we find will be in the Javadoc comment. It should be on the line immediately before the class name, method, or variable.

    Javadoc tags are nine in number:

    @ param
    @ return
    @ throws
    @ author
    @ version
    @ see
    @ since
    @ serial
    @ deprecated

    For more information on this, refer to the style guide in SUN. You can find it on their official site.

    More detailed information about JavaDoc

    @ param: parameters of the method
    The @ param tag is used to learn the parameter of the method. Behind the tag, it must learn the name parameter (its type will be automatically included in the Javadoc).
    Here is an source code example
    Code:
    /**
     * Met today the lev of Member.
     * * @ param lev
     *            The new lev of Member.
     */
    protected void setlev(SDZLevel lev) {
            this. lev = lev;
    }
    @ return: the object returned by the method
    The @ return tag is used to inform the object returned by the method.
    Here is an source code example
    Code:
    /**
     * Returns the lev of zero.
     * 
     * @ return A Instance of SDZLevel, who corresponds to lev of Member on SDZ.
     */
    Public SDZLevel getLevel() {
            return lev;
    }
    @ throws: exceptions propagated
    The @ throws tag indicates the presence of an exception to be propagated if it rises. We must specify the type of exception and the reason for the exception.
    Here is an source code example
    Code:
    /**
     * Returns the address of profile of Zero.
     * 
     * @ return the URL of profile of Zero, generated to from of l'id of Zero.
     * 
     * @ throws MalformedURLException  If never url is evil formed. 
     */
    Public URL getURLProfil() throws MalformedURLException{
            URL url = new URL("http://www.example.com/membres-258-"+id+". html");
            return url;
    }

  4. #4
    Join Date
    Feb 2010
    Posts
    136

    Re: JavaDoc Tool for Documentation

    @ author and @ version:
    It defines the author and the version number of class. The @ author tag informs the author's name of the class. The @ version tag indicates the version number of the class. This tag is then used by the @ since tag. These tags can not be used for methods.
    Here is a source code example
    Code:
    package example.test.javadoc;
    
    /**
     * Zero is the Class representative a Member of Website of Zero.
     * 
     * @ author someone
     * @ version 3.0
     */
    Public class Zero {
    
    [...]
    
    }
    @ see:
    This referring to another method, class, etc.. Tag @ see can make a reference to another method, class, etc.. Concretely, this is symbolized by a hyperlink in the Javadoc. So one of the most important tags.
    Here is the source code example
    Code:
    /**
     * The "lev" of Zero. This "lev" may be Amended.
     * 
     * @ see SDZLevel
     */
    private SDZLevel lev;
    @ since:
    This means from which version. The @ since tag allows us to date the presence of a method, a parameter. Behind this tag, note the version number of the class.
    Here is the source code example
    Code:
    /**
     * Met to day the nicknm of Member.
     * 
     * @ since 3.0
     */
    Public void setPseudo(String nicknm) {
            this. nicknm = nicknm;
    }
    @ deprecated:
    This indicates that a method is deprecated. The @ deprecated tag should describe the version from which the method / class is deprecated. But also what to use instead.
    Here is the source code example

    Code:
    /**
     * Returns the list of friends of zero.
     *
     * @ deprecated Since Java 1.4, replaced by getList()
     */
    protected vec<Zero> getvec(){
            vec<Zero> vector = new vec<Zero>();
            for (Z Zero: list){
                    vector.add(z);
            }
            return vec;
    }

  5. #5
    Join Date
    Feb 2010
    Posts
    136

    Re: JavaDoc Tool for Documentation

    3. The Writing Conventions

    There are conventions for the formatting of Javadoc. They concern the tags first, and reviews other. But there are also HTML in it.

    The general conventions
    There is plenty of advice for the layout of Javadoc comments. Here are the main ones:

    - The first sentence Javadoc of the class should be a short description of the class.
    - This advice also applies to methods, variables, etc..
    - Keep sentences relatively short.
    - Use the third person to comment on a method.
    - Cut the operation (algo) methods if necessary.
    - Using "this" rather than "the".
    - Tags @ param and @ return must be systematically identified (except methods without parameters or methods void).

    About HTML?!
    You can use HTML in your JavaDoc. But it should be used only for simple things. Do not try to do too much, this is not the goal. The most used tags are NEWS, <i>, and <ul> <p>. You can format the documentation with the CSS style sheet. You can also change the colors, this should simple.


    4. Conclusion

    As you must have been reporting, the Javadoc is a great tool for documenting Java code easily. While this may seem a bit heavy at the beginning, with some even say it's irrelevant, but if you make a habit of commenting on all your classes, all your methods, you will realize how this tool facilitates the maintenance of application. Yes you lose some time to comment on your methods, but you win when it comes to code re-usage. Indeed, no need to read hundreds of lines of code to understand the way a particular method.

Similar Threads

  1. Need help in EXIM Documentation Project
    By AADI-JI in forum Education Career and Job Discussions
    Replies: 5
    Last Post: 19-11-2010, 12:41 PM
  2. What procedure and documentation need for export
    By Adriana_andros in forum Education Career and Job Discussions
    Replies: 4
    Last Post: 17-11-2010, 07:37 PM
  3. Adobe CMM Documentation
    By Its_Shaili in forum Windows Software
    Replies: 6
    Last Post: 27-06-2010, 05:38 AM
  4. Integrating javadoc in jar to make it visible in eclipse
    By Amie in forum Software Development
    Replies: 5
    Last Post: 16-01-2010, 01:14 PM
  5. Bcedit.exe official MS documentation ?
    By Haerviu in forum Vista Setup and Install
    Replies: 1
    Last Post: 01-04-2007, 07:25 PM

Tags for this Thread

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
Page generated in 1,711,694,413.20427 seconds with 17 queries