Walkthrough: Creating XML Documentation in Microsoft Dynamics AX [AX 2012]
Updated: March 22, 2011
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
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.
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.
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."
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."
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.
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.
Announcements: New book: "Inside Microsoft Dynamics AX 2012 R3" now available. Get your copy at the MS Press Store.