Anyone interested in developer documentation of X++ code?


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.


But who really cares about this? Great tools won’t make my day – I want documentation!

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.

Comments (8)

  1. axcoder says:

    Very nice!

  2. axcoder says:

    I think there wold be good to chacnge contecnt delivery technology to some client-server one like it was in 3.0

  3. I think there would be good to create Documentation like Wikipedia in the public Web and integrate it with Dynamics AX 2009. Most of AX professionals will have possibility to write descriptions and documentation for classes/methods/tables in different parts of Ax code. There could be an official team from MS who could check and edit this documentation to meet industrial standards.

    in this case time to document code will be shorter than 15 years and will be less in cost.

  4. Chris Rothery says:

    Sounds good.  We’ve just started to work with 2009 so will be checking this inline documentation out.

    The tool to extract the documentation so that we can put it on our intranet sounds really useful.  Is it publicly available?

  5. msmfp says:

    The extraction tool is a part of AX – so yes, it is publicly available.

  6. 🙂 had a feeling as I wrote that that I should have looked in Ax’s menus before posting.  

    Thanks for the swift reply.  

    While I’ve got your attention, I’ve replied on your combinexpo’s post in the past and we’re scheduled to look at our update/build process shortly.  Is the version of combinexpos.exe that’s on there the latest and greatest version?  (I’ve added my email address as my url for this comment if you’d prefer this discussion to move away from the blog).

    Thanks

    Chris

  7. Jeff says:

    Finally a tool enables extraction of the documentation, so it can be processed outside AX, e.g. for publishing on MSDN

    Where is the tool? thx

  8. matthewklestrup says:

    I have found a xslt file that more or less works with the basic documentation xml file (sorting is not so pretty). But I need one as well for the reflection file. Can you help me?

    Thanks.