Jul 4, 2011 at 3:15 AM
Edited Jul 4, 2011 at 3:16 AM
The short answer is, the current Sandcastle style for the API documentation will not give you that.
I know you have seen it in the MSDN and so let give you the long answer...
Note: This assumes you understand how the Sandcastle works, if not just take the short answer...
For MSDN documentations, MS uses extensive tools including the Sandcastle to produce the final result.
For the API documentation, MS does not use the XML Docs, which all of us use. They have tools that extra
the documentations from various sources (which might include the XML Doc comments) to create conceptual
topics. In particular, the reference conceptual topics and build that with the Sandcastle tools.
The reference conceptual topics are compiled with the main_reference.xsl transformation style. We build our
documentations with the main_sandcastle.xsl transformation style. The results are currently different, so to get
that result we might have to migrate some features from the reference conceptual build to reference build.
This explanation applies to the question posted long ago in this thread...
Can sandcastle generate XAML dependency Property Information section?
Now, consider the current TransformComponent in the sandcastle.config file (which is used for the API documentation)
<component type="Microsoft.Ddue.Tools.TransformComponent" assembly="BuildComponents.dll">
<argument key="metadata" value="true" />
<language label="VisualBasic" name="VisualBasic" style="vb" />
<language label="CSharp" name="CSharp" style="cs" />
<language label="ManagedCPlusPlus" name="ManagedCPlusPlus" style="cpp" />
Changing the main_sandcastle.xsl transformation style to
main_reference.xsl will actually give you that
property value display. Take a look at the following result...
Property Value Test
But as you can see from the result, the comments are missing. The
main_reference.xsl uses a difference
configuration file, and therefore not meant for such uses.
For sometime now, I have being trying to use main_reference.xsl instead of the
the API documentations, but I will need to completely determine all the problems associated with this
and try to fix them. Otherwise the best option will be to update the main_sandcastle.xsl.