Best Practices: XML Documentation

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

Microsoft Dynamics AX conducts a best practices check of the XML comments to make sure that you provide documentation in the appropriate tags. For information about how to set the options for best practice checks, see Best practice parameters.

Best Practice Checks

The following table lists the best practices error messages and how to fix the errors.

Message	Message type	How to fix the error or warning
Tag '%1' in XML documentation is not supported.	Warning	Add XML documentation. For information about how to add XML documentation, see How to: Add XML Documentation to X++ Source Code. Because this is a warning instead of an error, this is optional.
Unsupported tag '%1' in XML documentation.	Error or Warning	Check the casing of the XML tags if this is reported as an error. If this is reported as a warning, an unsupported tag is present. Remove unsupported tags.
Missing tag '<param name="%1">' in XML documentation.	Error	Add <param> tags to the XML header template. The <param> tag must have a name attribute. The value of the attribute is case-sensitive and must match the casing in the method.
Missing tag 'returns' in XML documentation.	Error	Add <returns> tags to the XML header template.
Missing tag 'summary' in XML documentation.	Error	Add <summary> tags to the XML header template.
Tag '%1' exists more than once in XML documentation.	Error	Delete extra tags. This applies only when multiple tags are not appropriate.
Tag '<param name="%1">' has no content in XML documentation.	Error	Add a description of the parameter between the <param> tags.
Tag '<param name="%1">' in XML documentation doesn't match actual implementation.	Error	Fix the value of the name attribute. It is case-sensitive and must match the casing in the method.
Tag 'exception' has no content in XML documentation.	Error	Add a description of the exception between the <exception> tags.
Tag 'permission' has no content in XML documentation.	Error	Add a description of the required permission between the <permission> tags.
Tag 'remarks' has no content in XML documentation.	Error	Add content between the <remarks> tags or delete the <remarks> tags.
Tag 'returns' has no content in XML documentation.	Error	Add a description of the return value between the <returns> tags.
Tag 'returns' in XML documentation doesn't match actual implementation.	Error	Delete the <returns> tags and the description of the return value.
Tag 'summary' has no content in XML documentation.	Error	Add a topic summary between the <summary> tags.
XML documentation is not well-formed.	Error	Make sure that there are no mistakes in the XML tags. Each opening tag must have a corresponding closing tag.
Tag 'seealso' has no content in XML documentation.	Error	Add content between the <seealso> tags or delete the <seealso> tags.
No XML documentation for this method.	Error	XML documentation has not been written for this method.

See also

XML Documentation

XML Documentation Tags

XML Documentation Overview

How to: Add XML Documentation to X++ Source Code

How to: Generate XML Documentation Files

Walkthrough: Creating XML Documentation in Microsoft Dynamics AX

Announcements: New book: "Inside Microsoft Dynamics AX 2012 R3" now available. Get your copy at the MS Press Store.