The API documentation has grown tremendously
When I started to create the MSDN style help file 2 years back (the help files for DNN 4.8.4), the resulting .chm file was about 10Mb in size. For the current DNN 5.5, the help file has grown from 10Mb to almost 30Mb!
The documentation grew, because DNN developers, and also the DNN Corp. developers, spend more time on putting structured documentation right into the (new and enhanced) source code. The community benefits from the work of the employees of DNN Corp!
Work of the Reference team
But it was not only DNN Corp. developers who documented source code. Also, in the DNN Reference team, we assigned ourselves tasks to improve the existing documentation (or should I say: create the missing documentation).
I used one of the main base classes of the DNN (PortalInfo.vb) to create the standard for source code documentation.
If you have a look at an “old” version of the MSDN style help file (have a look at an old download from http://dnnhelpsystem.codeplex.com/), you will find meagre and missing documentation in the entry PortalInfo Class at the main entry DotNetNuke.Entities.Portals. This is how it looks in the old (DNN 484) .chm help file:
Documentation is missing (the red text) and for the rest it is mostly only the automatically generated docs that is available, not much additional code comments have been added by the original developers of de code.
The improvement of PortalInfo.vb
I spend quit some time to create a standard how we would the API documentation to be: a well documented class, methods and properties. And, if possible, examples how to use that part of the API. And we (the DNN Reference team) are proud of the result.
As mentioned, I used PortalInfo class as THE example, you can find the source of this class in the folder ~\Solution\Library\Entities\Portal\PortalInfo.vb of the source pack of DNN.
If you have a look at the same PortalInfo Class documentation in the newly generated MSDN Style help file of DNN 5.5, you will find an abundance of API documentation, well ordered, structured, including see also, examples of use and more.
Help file and intellisense both improved
If you compare the sources of PortalInfo.vb of DNN 5.5 with e.g. DNN DNN 5.0, you will see that all the info for the MSDN Style help file can be found as comment lines in the source code of PortalInfo.vb. This way, the documentation will not only be part of the (separate) MSDN style help file, it will also be part of intellisense in Visual Studio, if you are developing against DNN 5.5. The intellisense is contained within the XML documentation files that are (since DNN 5.2.0) distributed as part of a DNN release.
So our efforts for documentation multiplies itself: both into the .chm MSDN style help file as well as into the intellisense in Visual Studio.
But there is more
Tags van Technorati:
#dnnref! In the last part of this blogs series I will illustrate how YOU can help in this process.