inheritdoc with generic base

Topics: User Forum
Nov 8, 2010 at 9:07 PM

I am trying to use inheritdoc with members of a struct implementing ISet<T> for some T (ISet<int> in the test case below). Documentation only seems to be inherited for Clear(), but documentation for methods which refer to T (=int) in their signature do not inherit the documentation. Is that expected behavior? Is there some workaround? I do understand that there are issues such as having to potentially replace types (T => int) in the inherited documentation, but it would be great if that could be automated.

using System;
using System.Collections;
using System.Collections.Generic;

public struct SetDocumentation : ISet<int>
{
        public IEnumerator<int> GetEnumerator()
        {
            throw new NotImplementedException();
        }

        IEnumerator IEnumerable.GetEnumerator()
        {
            return this.GetEnumerator();
        }

        void ICollection<int>.Add(int item)
        {
            throw new NotImplementedException();
        }

        public void UnionWith(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public void IntersectWith(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public void ExceptWith(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public void SymmetricExceptWith(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public bool IsSubsetOf(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public bool IsSupersetOf(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public bool IsProperSupersetOf(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public bool IsProperSubsetOf(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        public bool Overlaps(IEnumerable<int> other)
        {
            throw new NotImplementedException();
        }

        /// <inheritdoc/>
public bool SetEquals(IEnumerable<int> other) { throw new NotImplementedException(); }         /// <inheritdoc/>
public bool Add(int item) { throw new NotImplementedException(); } /// <inheritdoc/> public void Clear() { throw new NotImplementedException(); } public bool Contains(int item) { throw new NotImplementedException(); } public void CopyTo(int[] array, int arrayIndex) { throw new NotImplementedException(); } public bool Remove(int item) { throw new NotImplementedException(); } public int Count { get { throw new NotImplementedException(); } } public bool IsReadOnly { get { throw new NotImplementedException(); } } }

I am using inheritdoc with SHFB 1.9.1.0, Sandcastle Styles patch 10621.1 Rev. 1 and VS 2010. The FrameworkVersion is set to 4.0.30319.

Coordinator
Nov 9, 2010 at 4:54 PM

I'll take a look into this when I get some time.  The members for documenation inheritance are matched up by ID.  Since the compiler generates the concrete instances of the generic classes, their IDs probably won't match anything in the comments files (i.e. the IDs for Set<int> won't match Set<T>).  If that is the problem, I'll see if there's a way to make the ID generic again and search for a match that way.

Eric

 

Coordinator
Jan 16, 2011 at 2:25 AM

I took a look at this issue and it turns out SHFB wasn't correctly locating the .NET 4.0 Framework XML comments files.  After adding code to fix that, all but one ISet<T> member was documented and that was due to a bug in MRefBuilder where it isn't currently generating correct API ID values when the member contains generics.  In this case, it was an private, explicitly implemented member so it wouldn't show up anyway unless you were documenting privates.  The fix will be in the next release.

Eric