DevForce Classic: Class Documentation

Class Documentation

Printed From: IdeaBlade
Category: DevForce
Forum Name: DevForce Classic
Forum Discription: For .NET 2.0
URL: http://www.ideablade.com/forum/forum_posts.asp?TID=364
Printed Date: 11-Jun-2026 at 1:38pm

Topic: Class Documentation

Posted By: rclarke
Subject: Class Documentation
Date Posted: 09-Aug-2007 at 8:16am

I would like to use Sandcastle to provide documentation for my model classes. The only way I see to do this is to override each property in the final class which is a lot of additional work and I'm not so sure it's a good idea anyway. Unless I'm missing something, there is no other quick way to do it. If anyone has any ideas please post them.

Replies:

Posted By: m2r4miller
Date Posted: 10-Sep-2007 at 9:43am

Download and install the following:

1. HTML Help workshop: http://msdn2.microsoft.com/en-us/library/ms669985.aspx - http://msdn2.microsoft.com/en-us/library/ms669985.aspx

2. Sandcastle June CTP: http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en - http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

3. Sandcastle Help File Builder GUI tool: http://www.codeplex.com/SHFB - http://www.codeplex.com/SHFB

In Visual Studio 2005, right click your Model project, select Properties, then the Build tab, and check the XML Documentation File box in the Output section.

Next Build your Model project, and run the Sandcastle GUI. Select the Model.XML in the \bin\debug|release folder and build the file.

It takes a while, but works very well.

-Mark

Posted By: rclarke
Date Posted: 04-Oct-2007 at 2:16pm

Mark,

I guess my original message was not clear. I know how to use Sandcastle. I would like to have a way to use Sandcastle to document properties within entities. The only way I know how to do this is to override every property in the final class just for purposes of adding the XML comments. What would be really cool is if Ideablade could capture the database column description and generate an XML comment in the <Entity>DataRow class for each property.

Posted By: m2r4miller
Date Posted: 05-Oct-2007 at 8:32am

Yes, that would be wonderful if they would capture the Description property of the table in comments as I use that property alot in my database designs.

We can hope, eh?

-------------
-Mark
mailto:mark@msdcweb.com - Email
http://markdmiller.spaces.live.com/default.aspx - Blog

Posted By: jforgan
Date Posted: 22-Nov-2007 at 2:39pm

We've developed an 'orm documentor' app which reads the DevForce .orm file and generates all the overrides and puts them in a .cs file. It generates complete 'skeleton' classes which include the property and relation property definitions along with comment sections.

We then include the .cs file in our solution and edit it to add the comments to each property.

If we re-run our documentor we can point it to our existing .cs file so that it picks up any existing comments and includes them against the relevant property when the file is regenerated.

At the very least it would be great if the ORM allowed you to define a comment against a property. Would seem to be a fairly simple enhancment because it's just some text that gets saved away in the .orm xml file - no validation required!

Posted By: rclarke
Date Posted: 25-Nov-2007 at 8:34am

I like the idea of being able to add a commnt for a property in the mapper but I think that the initial comment should be derrived from the database description field for the column. This way database documentation tools that produce documentation would still work and the same comments could be captured by the mapper and the programmer could augment or replace the comments in the mapper.

BTW, would you consider making your 'ORM Documentor' available?

Posted By: eileenv
Date Posted: 26-Nov-2007 at 6:04pm

Capturing the Description field from the database table is currently on our Features list. As we are working on our next generation Object Mapper, this feature will most likely be made available in version 4.x.