HOW TO: Generate Documentation Comments in Visual J# .NET (818445)

SUMMARY

This step-by-step article describes how to generate documentation Web pages for Javadoc comments in Visual J# .NET code.

Visual J# .NET supports documentation for Javadoc comments. However, you can only generate documentation Web pages in the Visual Studio .NET IDE.

Note There is no command-line utility to generate documentation Web pages for Javadoc comments in Visual J# .NET code.

back to the top

Support for Autocompletion of Documentation Comments

When you type the opening characters of a Javadoc comment (/**) in the Visual J# .NET code editor, the editor automatically inserts the closing characters for the comment (*/) on the following line. The code editor also starts each line between the opening characters and the closing characters by using an asterisk (*) character.

Javadoc tags and Microsoft extensions directives start by using the @ character in Javadoc comments. When you type the @ character in a Javadoc comment in the Visual J# .NET code editor, an autocomplete list appears that includes both supported Javadoc tags and supported Microsoft extensions directives.

back to the top

Build Comment Web Pages

You can generate documentation from Javadoc comments in your Visual J# .NET code. To do this in the Visual Studio .NET, click Build Comment Web Pages on the Tools menu. For each item, the Summary and Description sections are built from the associated Javadoc comment by using the following:

• The first, or summary, sentence in a Javadoc comment.
• The remaining portion of a Javadoc comment (the remarks).

For methods and constructors, the @param tag and the @return Javadoc tags are used to build the comments for any parameters and return values. The @see tag, the @version tag, and the @author tag are ignored.
The generated comments also contain the base class, the access level of the class or member, the signatures of the functions, and a list of function overloads for each method.

back to the top

Step-by-Step Example

1. Start Visual Studio .NET.
2. On the File menu, point to New, and then click Project.
3. Under Project Types, click Visual J# Projects, and then click Console Application under Templates.
4. Name the project MyJSharpApplication, type C:\ in the Location text box, and then click OK.
5. In Class1.jsl, replace the existing code with the following sample code:

   /**
    * Class that represents an employee.
    * This class is used to represent an Employee through  
    * personal details.
    * 
    * @see      Employee
    * @version   1.0
    * @author   John
   
    */
   public class Employee
   {
   	/** 
   	 * Stores the name of the Employee.
   	 */
   	private String name;
   	/** 
   	 * Stores the address of the Employee.
   	 */
   	private String address;
   	/** 
   	 * Stores the Date of Birth of the Employee.
   	 */
   	private String dateOfBirth;
   	
   	/** Default constructor for Employee.
   	 * <em>It is recommended to use the constructor 
   	 * with three arguments.</em>
   	 */
   	public Employee()
   	{
   	}
   
   	/** Constructor for ComplexClass.
   	 * @param   Name    The value to set for the name of the Employee.
   	 * @param   Date of Birth     The value to set for the age of the Employee.
   	 * @param   Address	The value to set for the address of the Employee.
   	 */
   	public Employee(String name, String dateOfBirth, String address)
   	{
   		this.name = name;
   		this.dateOfBirth = dateOfBirth;
   		this.address = address;
   	}
   	
   	/**
   	 * Changes the address of the Employee.
   	 * @param newAddress  Changed address of the Employee
   	 */
   	public void ChangeAddress(String newAddress)
   	{
   		this.address = newAddress;
   	}
   }
   

6. On the Tools menu, click Build Comment Web Pages.
7. In the Build Comment Web Pages dialog box, click Build for entire Solution.
8. In the Save Web Pages In text box, type the path of the file name, and then click OK.

back to the top