Missing summaries for indexer for c++/cli project.

Topics: Developer Forum, User Forum
Jun 11, 2013 at 1:46 PM
Hi,
For an indexer like:
/// <summary>
/// Gets the <see cref="TTParameter"/> at the specified index.
/// </summary>
/// <param name="index">The zero-based index of the parameter to retrieve. </param>
/// <value>
/// The <see cref="TTParameter"/> at the specified index.
/// </value>
property TTParameter ^ default[int] {
  virtual TTParameter ^ get(int index) new {
    return m_TTParameters[index];
  }
  virtual void set(int index, TTParameter ^ value) {
    m_TTParameters[index] = value;
  }
}
I get
Warn: ShowMissingComponent: [P:TrueTime.Data.TTClient.TTParameterCollection.Item(System.Int32)] Missing <summary> documentation
in Sandcastle.

The xml file has the following content:
        <member name="P:TrueTime.Data.TTClient.TTParameterCollection.default(System.Int32)">
            <summary>
Gets the <see cref="T:TrueTime.Data.TTClient.TTParameter" /> at the specified index.
</summary>
            <param name="index">The zero-based index of the parameter to retrieve. </param>
            <value>
The <see cref="T:TrueTime.Data.TTClient.TTParameter" /> at the specified index.
</value>
Is there anyway I can get Sandcastle to map Item to default?
Jun 11, 2013 at 3:01 PM
Which version of the compiler are you using? With both Visual Studio 2008 SP1 and 2010 SP1, I got "Item(System.Int32)" rather than "default(System.Int32)" in the compiler-generated XML file, and it matched the binary too.

With VS2010 SP1, I then added [System::Runtime::CompilerServices::IndexerNameAttribute("Foonly")] to the property, and the name of the indexer changed in both the XML file and the binary. Perhaps you can use IndexerNameAttribute to rename the indexer to "Item". Such a change would break binary compatibility, though.

Alternatively, SHFB has a check box "Fix up method signature issues in C++ XML comments files", which runs the FixupComments method defined in SHFB\Source\SandcastleBuilderUtils\BuildEngine\XmlCommentsFile.cs. This method could perhaps be extended to replace ".default" with ".Item". I think it would be best to first understand the circumstances in which ".default" appears, though.
Jun 11, 2013 at 3:07 PM
I'm using VS2012 (Upgrade 2) and [Sandcastle Help File Builder, version 1.9.7.0]
C++ project against .Net 4.0 (A custom .Net Data Provider)

Doesn't matter whether the "Fix up method signature issues in C++ XML comments files is checked or not.
Jun 11, 2013 at 3:22 PM
Also tried adding
[System::Runtime::CompilerServices::IndexerNameAttribute("Item")] 
property TTParameter ^ default[int] {
but the xml still has references to .default
Jun 11, 2013 at 3:29 PM
Edited Jun 11, 2013 at 3:29 PM
Personally, I've largely given up on XML comments embedded in C++/CLI, because of several shortcomings:

http://connect.microsoft.com/VisualStudio/feedback/details/707939/c-cli-xml-comments-on-generic-classes
http://connect.microsoft.com/VisualStudio/feedback/details/625780/c-cli-xml-comments-cannot-reference-array
http://connect.microsoft.com/VisualStudio/feedback/details/411703/c-xml-comment-reference-to-unknown-symbol-hardcode-cref-impossible
http://msdn.microsoft.com/en-us/library/ms177241%28v=vs.100%29.aspx (single pass prevents forward references)

Instead, I set up an .xdc file, similar to what the C++/CLI compiler would generate, and edited it as text. Then changed the build system to insert the file to the XdcMake item group so that the XdcMake target reads it.
Coordinator
Jun 11, 2013 at 8:51 PM
The C++ compiler doesn't always name the XML comment member IDs the way they are specified in the assembly metadata thus they can differ from the member IDs generated by the C# and VB.NET compilers. The fix-up property only affects certain known cases mostly involving generics and another with use of interior_ptr. There are a couple of other cases that I never did get around to finding a workaround for as well. This one is a new case I don't recall seeing before. I may just write a plug-in that will handle the known cases and allow adding specific mappings to convert bad IDs to good ones at build time such as this one.

Eric
Jun 12, 2013 at 10:06 AM
That would be great Eric. :)

I also tried using
[System::Reflection::DefaultMemberAttribute("Item")]

but with same result, .default still is generated.
Jun 12, 2013 at 10:18 AM
How about [IndexerNameAttribute("default")]? If the name of the property in the XML file is always "default", this attribute might at least change the metadata to match that.
Jun 12, 2013 at 10:32 AM
If I understood the ECMA spec correctly, IndexerNameAttribute doesn't make it to the metadata but DefaultMemberAttribute do.

So I tried it again
[System::Reflection::DefaultMemberAttribute("Item")] 
  public ref class TTParameterCollection sealed : DbParameterCollection {
...
    property TTParameter ^ Item[String ^] {
...
and it works! I forgot to rename
property TTParameter ^ default[String ^] {
to
property TTParameter ^ Item[String ^] {
in my first attempt. doh!

This is good enough for me, thanks for the input guys.

Regards/
Michael
Sep 12, 2014 at 12:20 PM
Hello,
I seem to be having the same problem but for classes with 2 indexers. The code looks like this:
property IMyTable^ default[int]
{
    IMyTable^ get(int index);
}

property IMyTable^ default[System::String^]
{
      IMyTable^ get(System::String^ name);
}
The XML documentation output looks like this:
<member name="P:IMyTableList.default(System.String)">

<member name="P:IMyTableList.Item(System.Int32)">
As you can see the XML documentation is correctly replacing the word "default" with "Item" in one instance but not the other. In the .dll they are both called "Item" so SHFB only recognizes one of them. Has anyone found a solution for this? I googled this for about 2 hours and only found this post. I would really like to find a solution with changing the code as that is not an option.

In EWoodruf's comment he says
I may just write a plug-in that will handle the known cases and allow adding specific mappings to convert bad IDs to good ones at build time such as this one.
Has there been any progres on this or?
Thanks for any input,
Seth
Coordinator
Sep 14, 2014 at 8:35 PM
I haven't done it yet. I'll see if I can get it into the next release.

Eric