How to use <value> to disply in help file the text: Property Value instead of Field Value

Jul 3, 2011 at 10:52 PM
Edited Jul 3, 2011 at 11:07 PM

Hello All!

Example:

protected ControlAdapter Adapter { get; }

Property Value

Type: System.Web.UI.Adapters.ControlAdapter
 A ControlAdapter for this control. If the target browser does not require an adapter, returns null.

Elena.

Jul 4, 2011 at 3:15 AM
Edited Jul 4, 2011 at 3:16 AM

Hello Elena,
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">
  <transform file="%DXROOT%\Presentation\vs2005\Transforms\main_sandcastle.xsl">
	<argument key="metadata" value="true" />
	 <argument key="languages">
	  <language label="VisualBasic" name="VisualBasic" style="vb" />
	  <language label="CSharp" name="CSharp" style="cs" />
	  <language label="ManagedCPlusPlus" name="ManagedCPlusPlus" style="cpp" />
	  <language label="JavaScript" name="JavaScript" style="cs" />
	</argument>
  </transform>
</component>

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 main_sandcastle.xsl for
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.

Best regards,
Paul. 

Jul 4, 2011 at 6:58 AM
Edited Jul 4, 2011 at 7:02 AM

Hello Elena,

I have worked out a quick fix for you. Change the ff. templates in the main_sandcastle.xsl as follows

 

<xsl:template match="value">
<xsl:call-template name="subSection">
  <xsl:with-param name="title">
    <include item="propertyValueTitle" />
  </xsl:with-param>
  <xsl:with-param name="content">
      <include item="typeLink">
          <parameter>
              <referenceLink target="{/document/reference/returns/type/@api}" qualified="true"/>
          </parameter>
      </include>
      <br />
      <xsl:apply-templates />
  </xsl:with-param>
</xsl:call-template>
</xsl:template>

<xsl:template match="returns">
<xsl:call-template name="subSection">
  <xsl:with-param name="title">
    <include item="methodValueTitle" />
  </xsl:with-param>
  <xsl:with-param name="content">
      <include item="typeLink">
          <parameter>
              <referenceLink target="{/document/reference/returns/type/@api}" qualified="true"/>
          </parameter>
      </include>
      <br />
      <xsl:apply-templates />
  </xsl:with-param>
</xsl:call-template>
</xsl:template>

 

The bold grayed portions are the extensions to provide that feature for both the "value" and "returns" parts.
The returns part will provide that support for the methods too. Method parameter types are already supported.

NOTE: The main_sandcastle.xsl file in the ..\Sandcastle\Presentation\vs2005\transforms directory.

Best regards,
Paul.