Auto-creating documentation -- c#

CyberMan_(MCDST)_nuub
3/20/2008 4:43:02 PM

SandCastle - Look for that...

Its the right path

--
If I can help, I will.
Do the same for a stranger today.

[quoted text, click to view]

K Viltersten
3/20/2008 11:32:09 PM

Is there a facility in VS Express to
automatically create an API-doc?

I could use the fairly OK Doxygen but
i'd prefer to use something from MS.

--
Regards
Konrad Viltersten
--------------------------------
sleep - a substitute for coffee for the poor
ambition - lack of sense to be lazy

K Viltersten
3/21/2008 2:48:38 AM

[quoted text, click to view]

I've received a number of suggestions mentioning
numerous solutions. None of them is a functionality
built-in for VS. That's surprising...

I though some HTML or XML would be created
during the process of compiling...

--
Regards
Konrad Viltersten
--------------------------------
sleep - a substitute for coffee for the poor
ambition - lack of sense to be lazy

Andy
3/21/2008 7:01:36 AM

[quoted text, click to view]

you should have xml comments in your source..

/// <summary>Converts a string to an int.</summary>
/// <param name="strVal">The <see cref="System.String"/> value to
convert.</param>
/// <returns>An <see cref="Int32"/>.</returns>
public int MyFunction( string strVal ) {

Andy
3/21/2008 7:02:11 AM

[quoted text, click to view]

Oh.. sorry. Then you need to turn on Generate xml comments, as
someone already described, and use SandCastle to convert your .xml

Gilles Kohl [MVP]
3/21/2008 7:59:34 AM

On Fri, 21 Mar 2008 02:48:38 +0100, "K Viltersten" <tmp1@viltersten.com>
[quoted text, click to view]

If memory serves, there used to be built-in functionality to generate HTML
help in VS2003, but that has been dropped in 2005, and did not come back.

[quoted text, click to view]

Well XML is indeed created - right-click your project and select Properties,
then go the Build tab. There, check "[x] XML documentation file".

An XML file with your comments (*) will be generated, but that is as far as it
goes, as far as I know.

It still makes sense to enable this IMHO, for two reasons:

- Intellisense - when e.g. calling a method of your own, you'll get your own
descriptions for what it does, for each parameter, for the return value ...

- Warnings - for each public element without a comment, you'll be reminded to
write one.

Regards,
Gilles.

(*): Enter a triple slash above a member (e.g. a method) in Visual Studio to

Jon Skeet [C# MVP]
3/21/2008 8:44:39 AM

[quoted text, click to view]

<snip>

[quoted text, click to view]

Do your types and methods have XML documentation defined for them
though? And are they public types/methods? I don't think documentation
is generated for non-public types, although I could be wrong.

--
Jon Skeet - <skeet@pobox.com>
http://www.pobox.com/~skeet Blog: http://www.msmvps.com/jon.skeet

K Viltersten
3/21/2008 9:44:40 AM

[quoted text, click to view]

Too bad...

[quoted text, click to view]

Perhaps i'm doing something wrong but the only
contents in the XML file i get is this.

<?xml version="1.0" ?>
- <doc>
- <assembly>
<name>TheCoolestProjectEver</name>
</assembly>
<members />
</doc>

The project consists of several classes and a number
of methods, so i was expecting the XML file to be
more... hmmm... larger.

--
Regards
Konrad Viltersten
--------------------------------
sleep - a substitute for coffee for the poor
ambition - lack of sense to be lazy

K Viltersten
3/21/2008 12:18:31 PM

[quoted text, click to view]

I miss JavaDocs... :)

Thanks to all. I'll try to get REALLY annoyed
and write one on my own. :)

--
Regards
Konrad Viltersten
--------------------------------
sleep - a substitute for coffee for the poor
ambition - lack of sense to be lazy

Got something to say? Click here to post a reply to this thread.

Don't see what you're looking for? Try a search.

View other messages about c#

c# : Auto-creating documentation