Method with a generic parameter

Topics: Developer Forum, User Forum
Jul 17, 2010 at 8:39 AM

I have a generic class, as follows, one of whose methods takes a generic parameter:

    /// <summary>
    /// This interface represents a list of nodes.
    /// </summary>
    /// <typeparam name="T">This is the type of item on the list,
    /// which is actually a <see cref="IDomNode"/>.</typeparam>
    /// <remarks>
    /// This is a read-only interface: you can use it to read the
    /// collection but not to change the collection.
    /// An instance of this type is returned by the <see cref="IDomNode.childNodes"/> property.
    /// <para>For further details, see the W3C
    /// <a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-536297177" target="_blank">NodeList</a>
    /// documentation.
    /// </para>
    /// </remarks>
    public interface IDomListT<T>
    {
        /// <summary>
        /// Returns the specified item in the collection.
        /// </summary>
        /// <param name="index">The index into the collection (for example, <c>0</c> to get the first item).</param>
        /// <returns>The item at the specified location in the list.</returns>
        /// <remarks>
        /// <note type="caution">The W3C documentation says,
        /// "If index is greater than or equal to the number of nodes in the list, this returns null."
        /// However in this API, passing in an invalid index value will result instead in an exception being thrown.</note>
        /// </remarks>
        T itemAt(int index);
        /// <summary>
        /// Returns the location (index) of the specified item in the list.
        /// </summary>
        /// <param name="item">A reference to an instance contained in the collection.</param>
        /// <returns>The zero-based index of the item in the collection.</returns>
        /// <remarks>This method throws <see cref="DomException.Code.NOT_FOUND_ERR"/> if the specified item cannot be found</remarks>.
        int indexOf(T item);
        /// <summary>
        /// Gets the list of items as an enumeration.
        /// </summary>
        IEnumerable<T> elements { get; }
        /// <summary>
        /// The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.
        /// </summary>
        int count { get; }
    }

 The documentation for the class and for all methods is generated correctly, except for the indexOf method.

SHFB emits warnings for the indexOf method:

  Info: BuildAssembler: Building topic T:ModelText.ModelDom.Nodes.IDomListT`1
  Info: BuildAssembler: Building topic AllMembers.T:ModelText.ModelDom.Nodes.IDomListT`1
  Info: BuildAssembler: Building topic Methods.T:ModelText.ModelDom.Nodes.IDomListT`1
  Info: BuildAssembler: Building topic Properties.T:ModelText.ModelDom.Nodes.IDomListT`1
  Info: BuildAssembler: Building topic P:ModelText.ModelDom.Nodes.IDomListT`1.count
  Info: BuildAssembler: Building topic P:ModelText.ModelDom.Nodes.IDomListT`1.elements
  Info: BuildAssembler: Building topic M:ModelText.ModelDom.Nodes.IDomListT`1.indexOf(`32)
  Warn: ShowMissingComponent: Missing <summary> documentation for M:ModelText.ModelDom.Nodes.IDomListT`1.indexOf(`32)
  Warn: ShowMissingComponent: Missing <returns> documentation for M:ModelText.ModelDom.Nodes.IDomListT`1.indexOf(`32)
  Warn: ShowMissingComponent: Missing <param name="item"/> documentation for M:ModelText.ModelDom.Nodes.IDomListT`1.indexOf(`32)
  Info: BuildAssembler: Building topic M:ModelText.ModelDom.Nodes.IDomListT`1.itemAt(System.Int32)

Note that the warning says that it's looking for a method which takes as its parameter something of type '32 (i.e. the 32nd generic parameter), wheres the class only takes one generic parameter.

The XML file from which it builds the documentation seems to me to be correct; it includes:

    <member name="M:ModelText.ModelDom.Nodes.IDomListT`1.indexOf(`0)">
      <summary>
            Returns the location (index) of the specified item in the list.
            </summary>
      <param name="item">A reference to an instance contained in the collection.</param>
      <returns>The zero-based index of the item in the collection.</returns>
      <remarks>This method throws <see cref="F:ModelText.ModelDom.Nodes.DomException.Code.NOT_FOUND_ERR" /> if the specified item cannot be found</remarks>.
        </member>
    <member name="P:ModelText.ModelDom.Nodes.IDomListT`1.elements">
      <summary>
            Gets the list of items as an enumeration.
            </summary>
    </member>

I didn't see this listed as one of the 5 currently-open issues.

Coordinator
Jul 17, 2010 at 8:41 PM

Check the Sandcastle project site as this would be a Sandcastle issue.  I believe there is an open work item for this issue or one similar to it.

Eric