Introduction
Documentation is one of the least-loved aspects of the world we live in. Writing code is mostly a lot of fun. Documentation, somehow, does not fit nicely under "fun"! However, as we all know, documenting your code is good practice, if only to save you from yourself! Visual Studio 2005 goes a long way towards making it easier to add while-you-code "documentation". Quite effortlessly, you can add descriptions for
- classes
- constructors
- properties
- methods
- method parameters
- values returned by methods
- fields (such as enums)
- ... etc.
of a class. From a developer's perspective, the most valuable payoff of doing this is -- all the descriptive information shows up in the marvelous intellisense popups.
Another hidden benefit of writing these descriptions is that by simply checking a single checkbox in Visual Studio's Project > app Properties > Build (where app is the name of your application) as shown in the picture above ... each time you build your application, Visual Studio will generate an XML file containing all your precious descriptions. Instantly.
The Good News
That's the good news. Indeed, you can use tools like Doxygen and Sandcastle to produce eminently presentable versions of your app.xml file.
The Not So Good News
The not so good news is using tools like Doxygen and Sandcastle involves a few "extra" steps. If you don't take those steps, unless you love XML, the automatically generated XML is not very user-friendly, because it looks something like this:
<doc>
<assembly>
<name>VVX_AppXmlViewer</name>
</assembly>
<members>
<member name="T:VVX_AppXmlViewer.Form_VVX_AppXmlView">
<summary>
Main form of this application
</summary>
</member>
<member name="M:VVX_AppXmlViewer.Form_VVX_AppXmlView.#ctor">
<summary>
The only constructor for this form
</summary>
</member>
<member name="M:VVX_AppXmlViewer.Form_VVX_AppXmlView.DoUpdateCaption">
<summary>
Refreshes the window's Caption/Title bar
</summary>
</member>
<member name="M:VVX_AppXmlViewer.Form_VVX_AppXmlView.
DoNavigateToInfoPage">
<summary>
Moves up the directory tree and locates the info HTML file
</summary>
</member>
<member name="M:VVX_AppXmlViewer.Form_VVX_AppXmlView.
DoGridCustomization(System.Windows.Forms.DataGridView)">
<summary>
Normally invoked once at startup
</summary>
<param name="dgv">The DataGridView to be customized</param>
</member>
<member name="M:VVX_AppXmlViewer.Form_VVX_AppXmlView.DoGridPopulate
(System.Windows.Forms.DataGridView,VVX.AppXmlDoc)">
<summary>
Invoked after an AppXml file is opened by user to display its contents
in a DataGridView
</summary>
<param name="dgv">DataGridView instance in which to display the data</param>
<param name="appXmlDoc">instance of
AppXmlDoc</param>
</member>
...
...
...
</members>
</doc>
The Need for AppXmlViewer
There doesn't seem to be anything between the above-mentioned extremes represented by the "good news" and the "bad news". But there are situations where you might wish there was something in between, such as ...
- You need to quickly scan through your own app.xml before sending it to someone else for any reason, perhaps to process through Doxygen
- You have downloaded source code from a web site like CodeProject and it came with an app.xml
- Your boss or colleague wants you to send him/her a single document (not a website) with all your descriptive information
- ...
The Goals for AppXmlViewer
- start the utility
- open an app.xml file
- scan it quickly in a human-friendly layout
- sometimes sort and/or filter in a few obvious ways
- quit the utility
and get back to what you enjoy doing most!
DISCLAIMER
I undertook this project to learn a few things about Visual Studio 2005, C#, XML, DataGridView, Application Doc XML, etc. Caveat Emptor: Nothing has been properly or adequately tested. More importantly, there is a good chance you or someone else can do this better. So, if you do use this code and cannot produce what you expect, there may be little I can do to help you. On the bright side, you have the source code and (though not easy to follow) technical reference material from Microsoft.
Useful References
Using the Application
Be sure to read the DISCLAIMER above before you do anything.
Main Window
The solution contains a tab control with two tabs:
- AppDocXML displays the XML file "as is" after you open it
- AppDocTable displays the parsed contents of the XML file in a
DataGridView table. It lists the contents of the member nodes of the XML, extracting and displaying data in the following columns:
- # a number for each member, mainly to help with sorting.
- Qualifier loosely describes the member (row), e.g., "Method".
- Type which is usually the first letter from the member's
name attribute. Mp identifies a row containing the param data type and any description you've provided, and Mr identifies a row containing the returns description you've provided.
- Namespace is the
namespace to which the member belongs.
- Class is the
class to which the member belongs.
- Name is the
name of the member (method, property, etc.).
- Summary is the
summary text you've provided.
Filtering the Member List
There are two ways in which you can shorten the list of members
- The View > Include > ... menu commands allow you to include/exclude various Types of members.
- The combobox lists the various classes found in the XML. If you choose All Classes, then all the appropriate members (i.e., based on the "Include..." criteria) will be listed. Alternatively, only those that match the selected class will be listed.
Printing
There is limited support for printing the table. It is largely lifted as is from another CodeProject utility: XmlStore Part 2: Printing DataGridView Contents.
Creating a PDF
In case you wish to create a PDF based on the contents of the DataGridView, you can export its contents using the File > Export > XmlStore menu command to create an XmlStore file and then use the utility provided in Creating PDF Tables using C# (.NET 2.0) and iTextSharp to create a PDF, encrypt, whatever. The resulting PDF can look like:
The latter also illustrates the use of watermark text and image.
Need an Integrated PDF Generator?
I did not integrate the PDF generator into this utility in part because I was not sure if there was any interest in it and in part because it would not run out-of-the-box -- you'd have to download the appropriate iTextSharp.DLL from SourceForge.net. However, if enough people post requests on the bulletin board below this article, I will try and build the PDF generator into this utility.
Source
This solution was created using Visual Studio 2005.
Building the Solution
If you have Visual Studio 2005, then you should be able to use the project source code "out of the box" -- simply build and run. The code itself is not rocket science. It is reasonably documented. If you don't have Visual Studio 2005, you will have to ask a more experienced friend. (Don't ask me, as I am a newbie! I am also clueless about VB.NET!!)
Code Modules
Side benefits of the code for newbies (like myself): the project includes modules with reasonably documented and self-explanatory code. With luck, they may help you learn how to use a few features of the sub-systems employed.
VVX_AppDocXml.cs
VVX.AppDocXml is a class used to translate the UI options described above and parse an app.XML file. It contains one main method, DoExtractMemberData(...). It is quite straightforward and reasonably documented. It essentially constructs an ArrayList of another fairly simple class (also in the same module) called VVX.AppXmlMember.
Form_VVX_AppXmlView.cs
This is the Form class for the utility. Most of it is fairly simple stuff. The one method worth noting is DoViewTableTabPageInit(). It uses the VVX.AppDocXml to parse an app.XML file, and then populates a DataGridView.
Other recent contributions
If any of these have helped you ...
Please consider sending in a donation to one of my favorite causes: Year Up, or to any similar NGO (non-governmental organization) in the world that is selflessly doing good work and helping people in need. Give a little, get a lot!
