Walkthrough: Creating XML Documentation in Microsoft Dynamics AX

Article
05/18/2015

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

You can document classes, class methods, and table methods in X++ source code by using XML documentation. You can generate an XML file from this XML documentation.

This walkthrough illustrates the following tasks:

Creating a project
Creating a class
Creating a method
Adding documentation to the method
Adding documentation to the class
Creating XML files for the project
Creating XML files for the entire application

Creating a Project

You can create XML documentation files for a project or for the entire application. In this procedure, you will create a project that contains the class and method for which you will create XML documentation.

To create a project

Open Microsoft Dynamics AX.
Press CTRL+SHIFT+P to open the Projects window.
In the Projects window, right-click the Shared node, point to New, and then click Project.

Note

The Shared node expands with a new project that has a name such as Project1.
Right-click Project1, select Rename, and then rename the class myProject.

Creating a Class

Next, you will create a class.

To create a class

Open myProject.
Right-click myProject, point to New, and then click Class.
In the Projects window, right-click the Shared node, point to New, and then click Project.

Note

The myProject node expands with a new class that has a name such as Class1.
Right-click Class1, select Rename, and then rename the class Math.

Creating a Method

In this procedure, you will create a method.

To create a method

Right-click Math and select New Method.
In the Code Editor, change the method to the following code.

        int add(int a, int b)
        {
            ;
            return a + b;
        }

Save the method.

Adding Documentation to the Method

Now you are ready to insert a header template into the method and write information between the XML tags.

To add documentation to the method

Click the Script button to access the Scripts shortcut menu, point to Scripts, point to documentation, and then click HeaderTemplate. XML tags will appear at the top of the code editor.
Below the <summary> tag, type a description of the method, such as "Adds two integers."
Below the <param name="a"> tag, type a description of the parameter, such as "The first integer to add." Add a similar description after the <param name="b"> tag.
Below the <returns> tag, type a description of the return value, such as "The sum of a and b."

Note

The parameter and returns tags were inserted because the method has parameters and a return value.
Below the <remarks> tag, add additional optional information, such as "An integer is a positive or negative whole number or zero."

Adding Documentation to the Class

In this procedure, you will insert a header template into the method and write information between the XML tags.

To add documentation to the class

Open the Math class.
Click the Script button to access the Scripts shortcut menu, point to Scripts, point to documentation, and then click HeaderTemplate. Alternatively, with your cursor positioned on an empty line above the code, type ///. XML tags will appear at the top of the code editor.
Below the <summary> tag, type a description of the class, such as "The Math class performs mathematical operations."
Below the <remarks> tag, add optional information, such as "This class contains the add method."

Creating XML Files for the Project

In this procedure, you will create an XML file that contains the documentation that you wrote in myProject, and an XML file that contains reflection information about the class and method in myProject.

To create XML files for the project

Create a folder in which you will create the XML documentation files. This procedure will reference a folder that has the path, C:\XMLDoc.
In the Projects window, right-click the myProject node, point to Add-Ins, and then click Extract XML documentation.
Select the Documentation and Reflection check boxes.
In the documentation File name field, type "C:\XMLDoc\documentation.xml".

Note

For security purposes, you may not be able to create XML files directly on the root directory.
In the reflection File name field, type "C:\XMLDoc\reflection.xml", and then click Okay. You can view the files at C:\XMLDoc.

Creating XML Files for the Entire Application

In this procedure, you will create an XML file that contains all of the documentation in the application, and an XML file that contains reflection information about all the objects in the application.

Note

The reflection file does not contain form information.

To create XML files for the whole application

Create a folder in which you will create the XML documentation files. This procedure will reference a folder that has the path, C:\XMLDoc.
Open the command prompt.
Type the following to create a documentation file for the whole application. Ax32.exe -startupcmd=xmldocumentation_C:\XMLDoc\documentation.xml
Type the following to create a reflection file for the whole application. Ax32.exe -startupcmd=xmlreflection_C:\XMLDoc\reflection.xml

Note

When you use these commands, Microsoft Dynamics AX will start and create the XML files. It will close when it finishes.