Auto-creating documentation

[K Viltersten]

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.

 

[CyberMan_(MCDST)_nuub]

SandCastle - Look for that...

Its the right path

 

[K Viltersten]

SandCastle - Look for that...

Its the right path

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...

 

[Gilles Kohl [MVP]]

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

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.

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

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
see how this works. See "XML Documentation" in help for more info.

 

[Jon Skeet [C# MVP]]

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.

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.

 

[K Viltersten]

I've received a number of suggestions mentioning

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.

Too bad...

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

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.

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.

 

[K Viltersten]

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.

I miss JavaDocs...

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

 

[Andy]

I miss JavaDocs...

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

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]

I miss JavaDocs...

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

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