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.
I feel like that guy in the Wendy's commercials who goes around promoting the restaurant as if he were with the company, but is in reality only a guy who loves their food.
DevTeach 2004 was excellent! DevTeach 2003 was excellent! And I am down for DevTeach 2005!
There are so many pluses about DevTeach. 1) held in Montreal 2) inexpensive 3) star presenters 4) interesting subjects 5) smaller group (not thousands like at TechEd) 6) get to meet and hang out with some of the best developers in the field who come to speak from all over the world 7) great food 8) begins over the weekend so you miss only two days of work 9) extremely wired 10) three days of sessions is just right
Just a fraction of the .NET track presenters include Jim Duffy, Don Kiely, Rod Paddock, Carl Franklin, Ted Neward, Tom Eberhard, Christian Weyer, Rob Howard, Kevin McNeish, I mean, geez, these guys dazzle.
So over the next few days I'll be putting the notes I compiled for each of the sessions I attended and some other stuff. The session notes will have a disclaimer that some of the info may be inaccurate because of my typing errors or my lack of understanding of the subject matter. The notes serve as a reference for me but may provide some value to those interested in the session topics. DevTeach policy is that session material is available online to registered attendees only, so I can't respond to any requests for session PPTs or source.
