Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Documenting using Sandcastle: Refering to enum value using <see>

I'm using Sandcastle 2.4.10520 and Sandcastle Help File Builder 1.8.0 to generate a .chm help file.

In my documentation, I'm using <see> tags.

If I try to refer an enum like <see cref="NumberStyles"/> it works perfectly.

If I try to refer an enum value like <see cref="NumberStyles.AllowTrailingWhite"/> I get a link in the documentation file, but the link leads me to an MSDN Page not found

I don't get any warnings - my xml documentation is correct.

I've noticed that MSDN pages that refer to an enum value also have a Page not found link. For example: UInt64.Parse Method (String, NumberStyles, IFormatProvider) refers to NumberStyles.AllowHexSpecifier and this leads to another MSDN Page not found.

Should I refer to the enum instead of the enum value?

What should I do to refer an enum? Is it even possible?

like image 600
brickner Avatar asked May 01 '10 14:05

brickner


1 Answers

The fact that it's happening on MSDN doesn't bode well. Do the enum values have XML documentation?

If I remember correctly, there should be settings in SHFB that will let you force generation of documentation for members that don't have XML - or maybe it's a setting that lets you exclude members that don't have XML doc. Regardless, give the settings a good once over to make sure you aren't excluding the enum members that way.

Otherwise, it should generate documentation for every member, and enum values are members of types the same as a const or static field would be.

EDIT: It looks like at least on the newer MSDN site, individual enum values aren't given their own page. For example, take a look at the NumberStyles enum. In that case, you might not have a better option than just linking to the enum.

like image 120
Daniel Schaffer Avatar answered Sep 19 '22 17:09

Daniel Schaffer