aspose file tools*
The moose likes Beginning Java and the fly likes My guide for learning JavaDoc for beginners - I need help and a review Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "My guide for learning JavaDoc for beginners - I need help and a review" Watch "My guide for learning JavaDoc for beginners - I need help and a review" New topic
Author

My guide for learning JavaDoc for beginners - I need help and a review

Andy Jack
Ranch Hand

Joined: Nov 22, 2012
Posts: 257
Hi ! I felt like making a JavaDoc guide which gives a quick and practical overview of how to create professional documentation for your code. Once people get an idea about what its all about, they can read the long and dry tutorials by oracle.
My question is at the bottom of the image. Please tell me the answer for that. BTW, why do i have to upload an image only from a web server ?

okay, here it goes:

What is java doc ? Please tell me quickly without making me read too much-
See attached image(made by me!!!)

Okay, now i get the picture. So, How do i create the JavaDocs for my classes ?
See the tutorial below (not made by me) -

<EDIT> Note - This video is meant for teaching you which buttons to click in Eclipse if you want it to make a javadoc for your code. Focus on that. If the speaker says something wrong like "apples are oranges" then ignore all that.
The goal is to know which buttons to click and see your javadoc take birth.



HTH

Thanks in advance








[Thumbnail for java.JPG]


Java Newbie with 72% in OCJP/SCJP - Super Confused Jobless Programmer.
I am a "newbie" too. Please verify my answers before you accept them.
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 38897
    
  23
You were right to disown creation of that tutorial; it has four errors in four minutes:-
  • 1: The quality of the descriptions is poor. For example the addCustomer method comment adds nothing that you can’t guess from the method name.
  • 2: The constructor was incorrectly described as “default”.
  • 3: There was a warning on the Eclipse console, which was not addressed.
  • 4: He points to the constructor and says method.
  • I cannot read your picture; please read this.
    Please don’t go writing tutorials until you know what you are doing yourself.
    Andy Jack
    Ranch Hand

    Joined: Nov 22, 2012
    Posts: 257
    Campbell Ritchie wrote:You were right to disown creation of that tutorial; it has four errors in four minutes:-
  • 1: The quality of the descriptions is poor. For example the addCustomer method comment adds nothing that you can’t guess from the method name.
  • 2: The constructor was incorrectly described as “default”.
  • 3: There was a warning on the Eclipse console, which was not addressed.
  • 4: He points to the constructor and says method.
  • I cannot read your picture; please read this.
    Please don’t go writing tutorials until you know what you are doing yourself.


    Oh !....I was focusing more on learning how to make eclipse generate javadocs, which the video enabled me to do. By the way, the image is very clear on my pc and could be made clear on yours too.
    Please try this - when you click the image, you might see a magnifying glass symbol over it. Please click that and the image will become big and crystal clear.
    I am sorry that I cannot post a doc. I had deleted the doc and the image too.

    Thanks.
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 38897
        
      23
    Andy Jack wrote: . . . the image is very clear on my pc and could be made clear on yours too. . . .
    Could be made clear? Maybe.
    Will be made clear? No.
    Agree that video does tell you how to use Eclipse for documentation comments, but it is not at all a good tutorial.
    Andy Jack
    Ranch Hand

    Joined: Nov 22, 2012
    Posts: 257
    @Campbell Ritchie - (when i say you, i dont mean you. i mean all the authors who go into too much details when its not needed)

    I wrote this tutorial because i was frustrated. Few books or tutorials have made me smile and smile for a long time. I thought that sometimes, we need to use this approach to teaching -

    1 - Give a quick overview with minimum technical detail. Make the student know what the topic is all about and why he should learn it.
    2 - Then dive into the details.

    I suspect that if we do 2 before 1, the student is overwhelmed with details and might even become disinterested. Let him taste the power of the subject by doing 1. If he likes it, he's going to come back for more - 2.

    Want to be a car mechanic ? The last thing you need is a lecture on combustion engines, chemical equations for combustion, aerodynamics etc !!!
    Why not get a quick idea of gas, brake, steering etc...drive a little and drive slowly under supervision. Then start discussing about the engine, lubricants, repairing
    flat tires etc. And please...dont talk about atoms and molecules..we are teaching someone how to be a mechanic and not a scientist.



    Andy Jack
    Ranch Hand

    Joined: Nov 22, 2012
    Posts: 257
    Campbell Ritchie wrote:
    Andy Jack wrote: . . . the image is very clear on my pc and could be made clear on yours too. . . .
    Could be made clear? Maybe.
    Will be made clear? No.
    Agree that video does tell you how to use Eclipse for documentation comments, but it is not at all a good tutorial.


    Anyway, i just found out that coderanch does not allow uploading .pdf, .docx files. I don't know why. So, i guess image is the only easy way out.
    Campbell Ritchie
    Sheriff

    Joined: Oct 13, 2005
    Posts: 38897
        
      23
    Andy Jack wrote: . . . Why not get a quick idea of gas, brake, steering etc... . . .
    And teach the customers how to pray, for when the brakes fail at 85mph

    To create documentation:-
    Apply documentation comments to every member of your class, your class itself and all its constructors. Forget that private members usually vanish when you create the documentation.
    Use the javadoc tool.
    Remember that once you have documented a particular feature, you cannot change it.
    You need to learn about the conventions about what you write, what the @ tags mean, etc.javadoc Foo.java
    Open the index.html file.
    I have introduced a deliberate error into the documentation comments. Find it.
    Andy Jack
    Ranch Hand

    Joined: Nov 22, 2012
    Posts: 257


    I think it should be named. Will give it a random name, compile, document and look for the error.
    Andy Jack
    Ranch Hand

    Joined: Nov 22, 2012
    Posts: 257
    I got a warning when I made the javadoc for your class.
    src\Foo.java:22: warning - @throws: is an unknown tag.

    Then, i searched google and got this

    java.lang.RuntimeException is a type of
    extended by java.lang.IllegalArgumentException or UncheckedException. You threw that in your code.

    Points worth noting -


    ..............
    Unchecked Exceptions :

    aren't typically placed in the method's throws clause.
    are very rarely caught by the caller.
    do not form part of the contract of the method, but rather represent what happens when the contract is broken. The caller cannot recover from such errors.
    almost always occur when a precondition on a parameter is not met. However, such conditions are almost always already documented in a @param tag.

    In almost all cases, a @throws tag simply repeats verbatim conditions already stated in a @param tag, and doesn't add in any way to the specification of the method's behavior. Such repetition should be regarded with grave suspicion. When a change occurs, it's far too easy to forget to update the javadoc in two separate places.

    A general comment regarding broken contracts can be stated once in the javadoc overview.html document :
    "If the requirements or promises of any method's contract are not fulfilled (that is, if there is a bug in either the method or its caller), then an unchecked exception will be thrown. The precise type of such an unchecked exception does not form part of any method's contract."


    Got it. Very humbling moment indeed. Thanks.




     
    jQuery in Action, 2nd edition
     
    subject: My guide for learning JavaDoc for beginners - I need help and a review