parameter Types of methods have double entries

Topics: User Forum
Apr 18, 2014 at 1:00 AM
Sandcastle 1.9.8.0 on Windows 7

In the output help files (.chm VS2010)
each method has a double entry for Type its properties, so it looks like this in the browser:
 Parameters
        serverIPAddress
        Type: System.String
        Type: String
        The IP address to the server.
The source xml for this portion is:
<param name="serverIPAddress">Type: <see cref="T:System.String" />
<para>The IP address to the server.</para></param>
The resultant HTML is this:
        <div id="parameters">
        <h4 class="subHeading">Parameters</h4>
            <dl paramName="serverIPAddress">
            <dt><span class="parameter">serverIPAddress</span></dt>
            <dd>Type: <span class="nolink">System<span id="ID0EBCADHCAAAAA"> </span>
                            <script type="text/javascript">
                            addToLanSpecTextIdSet("ID0EBCADHCAAAAA?vb=.|cpp=::|cs=.|fs=.|nu=.");</script>String</span><br />
                    <span>Type:<span class="nolink">String</span>
                    <p>The IP address to the server.</span></dt><dd>
Is there something I can do to get only one entry for Type?
(I don't understand why the ID and the javascript are added.)

Thank you for your time and help...
Coordinator
Apr 18, 2014 at 2:57 AM
The type is listed automatically by the presentation style which is true for all presentation styles. Your XML comments don't need to list it. The param element is mainly to describe the purpose of the parameter. The script is there to adjust the separators based on the currently selected language. It has more effect on array and generic types (List<T> for C# as opposed to List(Of T) for VB).

Eric
Apr 18, 2014 at 4:34 PM
Thank you for your quick attention Eric! I appreciate it.

I understand that "The param element is mainly to describe the purpose of the parameter."

When you say: Your XML comments don't need to list it [the value type].
Are you saying I don't need this bit in the XML?
Type: <see cref="T:System.String" 
Will Sandcastle still generate the type information without it?
We need the type information defined for each parameter of the method, like so:
Parameters
        serverIPAddress
          Type: String
          The IP address to the server.
What is odd is that when the Type for Properties is created in the HTML, there is no problem at all.
Example XML code for Properties:
        <member name="P:APDocConverter.IDocConverterDeprecated.NewDocumentName">
          <summary>
                Type: <see cref="T:System.String" /><para>Specifies the name of the output file after the conversion.</para>
                <remarks><para>Deprecated. Specify the output filename in the Convert methods.</para></remarks></summary>
        </member>
Resulting HTML code for property value information as viewed in browser:
    Property Value
        Type: String
HTML code produced by Sandcastle:
    <h4 class="subHeading">Property Value</h4>Type: <span class="nolink">String</span>
Now this XML code for Properties is just about identical to the XML code for Methods (see my first post),
And the output is just as expected, one instance of the parameter description.
(Also, there is no JavaScript and ID created.)

I wonder why Sandcastle handles what looks to be like identical XML structure so differently.
  • Is something I can do to get Sandcastle to treat the XML information for method parameters the same way it treats the XML code for properties parameters (one instance of the definition for Type)?
    *OR.. If I go through our IntelliSense and remove all the
Type: <see cref="T:System.String
Will I still get:
          Type: String 
in the output?

Thanks for your time and help,
Mary Ann
Apr 18, 2014 at 5:40 PM
I used a regex in NotePad ++ to delet all instances of "Type: <see cref= blah blah : />" in the XML file.
Type: <see cref="([^`]*?)" />
Once all these were gone, the double entries for Type:XXXX were gone.
The Type definitions are still there, with just one entry, just what we want.

I still wonder why the XML for the parameters for Properties works fine,
but not the parameters for Methods, since they use the same structure and syntax.

Oh well, I guess I'll just run this RexEx whenever I get a new XML file from the developers.

Thanks,
Mary Ann
Marked as answer by mashowell on 4/18/2014 at 9:41 AM
Coordinator
Apr 18, 2014 at 8:15 PM
Edited Apr 18, 2014 at 8:17 PM
You will still get duplicated type information for properties. However, in that case, the type information will appear in the summary at the top of the page since that's where the type info your developers entered in the comments appears. The automatically added type information will appear in the Property Value section as it does for parameters on methods. Since the presentation styles add the property, return, and parameter type info automatically, it would be less work for the developers since they would not have to add and maintain the type info in the comments.

To clarify, Sandcastle parses the assembly to get the API information. Type information for members comes from the assembly, not the comments.

Eric
Apr 21, 2014 at 5:38 PM
Thanks a lot for your quick help.
I am able to publish without the double entries now.

-- Mary Ann