A new feature in Dynamics AX 2009 enables developers to write developer documentation directly in the X++ Editor while writing the production code. The feature is very similar to the XML documentation feature in C#.
Basically any method can contain /// (triple-slash) comments followed by structured documentation in XML format. Here is an example:
The developer is assisted by a dynamic documentation template, which is inserted through an editor script. The template automatically builds a skeleton including all the required tags for the current method. On top of this the written documentation is validated by best practice rules; which effectively prevent the documentation from growing stale. Finally a tool enables extraction of the documentation, so it can be processed outside AX, e.g. for publishing on MSDN.
Dynamics AX 2009 contains about 125.000 table and class methods in the SYS layer. To give a perspective on this number, it will take you over 15 years to document them all, if you can document 5 methods an hour.
All the methods shipping with Dynamics AX 2009 will have some documentation:
- 10% will be available in the X++ source code, in the product documentation and on MSDN. This content has been written by developers for developers. (and reviewed by Content Publishing).
- 20% will only be available in the product documentation and on MSDN. This is pattern matched documentation for methods such as main(), construct(), pack(), unpack() and parm(). This documentation has been written once for each pattern, and then applied to all methods matching the pattern.
- 70% will only be available in the product documentation and on MSDN. This is automatically generated minimal documentation for methods that we haven't manually documented. It contains syntax and other high level information.
Or in other words:
- You will never see the dreaded boilerplate "At the time of publication..." again.
- About 40.000 methods contain human written developer documentation.