DevTeach2004 : Generating .NET Code Documentation
Generating .NET Code Documentation
Jean-Claude Manoli.
NET140
These session notes serve primarily to share the content of the session and as a reference for me. They may also provide some value to those interested in the session topics. Some of the information found in these notes may be inaccurate due to my typing errors or a lack of understanding of the subject matter. DevTeach policy is that session material is available online to registered attendees only, so I cannot respond to any requests for session PPTs or source.
NDoc is free, open source documentation builder.
NDoc uses reflection on compiled assemblies and their XML documentation files to produce a complete code documentation.
Works with any .NET language
Produces MSDN-style documentation to .CHM or VS.NET Help
Highlighting item and F1 retrieves your custom documentation.
Section Elements
<summary>
<remarks>
<para> for paragraph
<param name=...>
<returns>
<value>
<include file can store more doc info.> sweet.
Should grab the session materials for the use of the include file.
<example>
<coede lang="C#">
Static void Main()
{
Console.WriteLine(...)
Console.Read()
}
The example in the Documentation is shown verbatim.
<Exception>
Exception Type / Comments
<Seealso cref=...>
Block elements
<code> shown earlier
<list type=...>
<para>
<c> Code within a text paragraph
<paramref cref=> reference to a parameter
<se cref=...>Delimits text paragraphs in <remarks> or <example>
Summary: I can't believe I ended up in this session. A session on code comment generation, and more specifically, NDoc, was a great idea, though it has little relevance to me (yeah, I know. Documentation is never a bad thing...) I am glad I was able to see nDoc in action.
That said, it was the first session of the day at 8:00 AM. I didn't make it to the DevTeach area until 8:15 and figured I had 45 minutes to hang around the pastry table. (Note to self, knowing what time the first conference sessions start is helpful.)
So while zoning out a bit during the NDoc presentation I check out the schedule printout in my new DevTeach 2004 canvas briefcase. The other choices were 15 .NET controls in 75 minutes, new XML features in Yukon, and introduction to OLAP. Okay, .NET controls are cool, I'll go there.
The room names confused me, though. Joyce. Jarry. Lamartine. Musset. We're in Quebec, remember. So I walk into Jarry, thinking I was walking into Joyce.
I'm in the wrong room, but don't want to leave and appear rude to the presenter. NDoc is cool. I'll hang here. Geez, this coffee sure gets cold quick!
What's this? Object Relational Persistence for .NET in Lamartine??? Now? Damn.
Oh well, DevTeach sessions are online and available to all attendees, so I'll check it out then.
Jean-Claude's presentation was a little awkward and slow (English is obviously his 2nd language), but good materials and a good session. 8 of 10.