1 / 17

Javadoc

Javadoc. Prasad Perera COMP 249. Comments in Java. // Can be single line comments. /* More than one line. Useful to "erase" a block of code from compilation */. /** * A Javadoc comment * To generate nice HTML documentation */. What is Javadoc?.

guang
Download Presentation

Javadoc

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Javadoc Prasad Perera COMP 249

  2. Comments in Java // Can be single line comments /* More than one line. Useful to "erase" a block of code from compilation */ /** * A Javadoc comment * To generate nice HTML documentation */

  3. What is Javadoc? • A standard for documenting Java programs . • Allows you to attach descriptions to classes, constructors, fields, interfaces and methods in the generated html documentation by placing Javadoc comments directly before their declaration statements. • Ex: /** * * The Student class implements methods to calculate student grades. */ publicclass Student {

  4. Javadoc Compilation • javadoc.exe • Generates documentation of your Java classes in a standard format • Comes with the JDK. • For each X.java, it will create an X.html plus a couple of additional pages (index, ..)

  5. Javadoc Compilation Cont’d. • Basic command line compilation: • Javadoc [options] [files] • some basic Javadoc options -author -classpath [path]  / [path];[path]; -sourcepath [path] / -sourcepathlist  [path];[path]; -version • Ex: • c:\> Javadoc -version 1.1 -sourcepath C:\Mysources –classpath C:\Mylibs

  6. Javadoc Compilation Cont’d. • Generate javadoc using eclipse

  7. Generate javadoc using eclipse Cont’d.

  8. Javadoc files

  9. General form of a Javadoc comment /** * One sentence ending with a period describing the purpose. * Additional lines giving * more details (html tags can be included) * * javadoc tags to specify more specific information, * such as parameters and return values for a method * * @Tag Description ... * @Tag Description ... * */

  10. Tags • Allow you to specify specific information used in the HTML file • most common tags: • For files, classes and interfaces: @author Name @version Version number • For methods: @param name description @return description @exception exceptionClass description @deprecated description • For everything: @see relatedReference (ex. other class name)

  11. Documenting Java Files, Classes and Interfaces /** * The Student class implements methods to calculate student grades. * @authorprasad * @version 1.1 * @see String */ publicclass Student {

  12. Documenting Java Files, Classes and Interfaces Cont’d.

  13. Documenting Methods • Javadoccomments go immediately before the method definition • Common tags : • @param <name of parameter> <description> • @return <description> • ex: /** * Calculates the overall score for all the marks according to their weights * @parammidExamMark mid exam mark * @paramfinalExamMark final exam mark * @return The final score calculated */ publicdoublecalculateOverallScore(intmidExamMark, intfinalExamMark){

  14. Documenting Methods Cont’d.

  15. Javadoc Extra • Can add Html tags to the comments to add nicer formatting to the resulting document. • Advantages: • looks very nice… • provides a consistent look and feel to API documents • when source code is changed: • the Javadoc comments can be changed in the source, at the same time. • the external documentation is then easily re-generated.

  16. Javadoc Extra Cont’d. /** * <p style="font-family:algerian;color:blue;font-size:20px;">The Student class implements methods to calculate student grades. :)</p> * @authorprasad * @version 1.1 * @see String */ publicclass Student {

  17. References • Previous Javadoc tutorials (COMP 248) • http://students.cs.byu.edu/~cs240ta/fall2012/tutorials/javadoctutorial.html • http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

More Related