In Java we try not to read the source code, I may not have the source
        code. But I NEED to know how to use that code.
        
        I need to know:
           the class name
           the package name
           the method name
           the method parameters
           the return value form the method
           any exceptions thrown by the method
           
        so Java created a neat concept, put you documentation
        into the source code, then run a tool to generate the Docs
        
        this way anytime you change the source, I can update the docs automatically
        
        to add source level documenttion, we use the JavaDoc comments:
        /**
           here I code my doc comments,
           I can include HTML tags
           because the docs are gnerated as HTML pages
       */
       
       -----------------------------------------------
       JavaDoc Rules and Best Practices
       
       I SHOULD (the IRS requires it) document all public
          classes/methods/fields/etc
          
       the JavaDoc comment goes before the code it is commenting
       
       I can use older style HTML, I prefer newer style HTML
       
       <em>itallics</em>
       <strong>bold</strong>
       <ul>                      <- bulleted list (I could also use <ol> to get numbers)
          <li>list item</li>
          <li>list item</li>
       </ul>
       
       {@code <source code goes here> }  or I can use <code>java source code</code>
       
       
       -----------------------------------------------------------------------------
       JavaDoc Best Practices:
       
       1) the first line of the docs is the summary, and it needs to be a sentence 
           (with punctuation), the summary shows up in the Overview or Package docs
       2) add a <br> tag to insert a new line in the generated HTML 
       3) add examples as needed to show the code working, add an HTML <pre> tag
           to keep source code formated
       4) use HTML list tags <ul> bullets, <ol> numbers, with <li> List itme tags
           to create lists
       5) when documenting a Constructor show initial values
       6) when documenting a getter method, add the JavaDoc annotation
           @return <what it returns>
       7) when documenting a setter method, add the JavaDocs annotations
           @param <what is passed in>
           @throws <Exception class> <Exception details
       8) document all the business rules for the setter  
       
       optionally: I can document at the Package level via a package-info.java
                    class in the package, JavaDocs will pick it up (this can be
                    created via the new -> package wizard)
                   I can also create an overview.html file as the project overview
                     docs (I will need to click the Next button to set the Overview)


--------------------------------------------
In Eclipse please

1) select the FlightExample project
2) using the Project menu select Generate JavaDocs
3) verify the correct project is selected, and the location is the docs folder
    in the project
4) click finish and OK the setting of the docs folder
5) open the new docs folder and right click index.html
    and select Open With... -> Web Browser
    
this shows that JavaDocs is reading the source, however the generated HTML pages
are bare...