Add a way to inherit documentation <inheritdoc />

[gafter]

(moved from part of dotnet/roslyn#67 by @dfkeenan, with part of the request tracked at #315)

Hi,

Please add <inheritdoc /> tag or similar:

I think it would be really handy if the compiler(s) when outputting the documentation XML file if it could use inherited documentation where available/requested. Though I am not sure what should be output if there is no documentation available.

P.S. A Diagnostic and Code Fix that generates document comments for me would also great 😃

[daveaglick]

Should <inheritdoc /> and namespace comments be tracked in separate issues?

Also, FWIW, I have an open pull request at dotnet/roslyn#15494 that addresses namespace documentation comments as described in dotnet/roslyn#15474 (which hasn't been closed or migrated yet).

[gafter]

@daveaglick Yes, having separate issues would be great. If you create a new one for one of these and link to it here, I'll edit the OP here.

[daveaglick]

@gafter 👍

I created #315 which is just a copy of dotnet/roslyn#15474 (so I guess that corresponding Roslyn issue can also be closed now)

[terrajobst]

Is's worth mentioning that this tag can be (and already is) supported by documentation generators. By making it a Roslyn feature it makes it first class by making IntelliSense work (e.g. hovering over calls in the class overriding the member shows the documentation). Also, it should be implied to reduce boilerplate without causing a compiler warning for missing documentation.

[sharwell]

I believe a good way to start here would be examining the features currently provided by SHFB for this documentation element, and then identifying ones which would be impractical from an implementation perspective or "not particularly needed" from an overall usage perspective.

🔗 inheritdoc (Sandcastle XML Comments Guide)

Syntax

I believe it's reasonable to use the same form as defined by SHFB:

<inheritdoc [cref="member"] [select="xpath-filter-expr"] />

This element may be placed either as a top-level element or as an inline element in a documentation comment.

Compilation

The compiler is updated in the following ways to account for this element:

• The compiler MUST allow the use of an inheritdoc element as a top-level element in XML documentation comments
• The compiler MUST allow the use of an inheritdoc element as an inline element in XML documentation comments
• The compiler SHOULD report a warning if the inheritdoc element appears without a cref attribute, and no candidate for inheriting documentation exists
• The compiler MUST evaluate the cref attribute value in the same manner as it does for the see element, and include the resolved documentation ID as the value of the attribute in the output documentation file
• The compiler MAY report a warning if the select attribute is specified, but the value is not a syntactically valid XPath expression
• The compiler SHOULD preserve the placement and form of the inheritdoc element in the XML documentation file. It MUST NOT replace the inheritdoc element with inherited documentation when writing the documentation file. (Edit: This one is the subject of disagreement below; I plan to revisit after writing up a proposal for the Tools section.)

Candidate for inheritance

⚠️ Some items in this list are written as existence (Boolean), while others identify the actual candidate(s). This section should be cleaned up with the understanding that the compiler only needs to care about existence for the purpose of reporting a warning as described above.

• For types and interfaces
  • The type is derived from a class which is not System.ValueType, System.Enum, System.Delegate, or System.MulticastDelegate, OR
  • The type implements a named interface which is not itself
• For constructors
  • The containing type of the constructor is derived (directly or indirectly) from a type which contains a constructor with the same signature
• For explicit interface implementations
  • The candidate is the implemented interface member
• For overriding methods (methods marked with override
  • The candidate is the overridden method
• For implicit interface implementations
  • The candidates are the implemented interface members

Impacted warnings

The following warnings, which are specific to the Roslyn implementation of a compiler for C#, should be updated to account for this feature:

CS1573

Parameter 'parameter' has no matching param tag in the XML comment for 'parameter' (but other parameters do)

Care should be taken to not report this warning in the following scenario. It would be sufficient to disable this warning any time inheritdoc appears as a top-level documentation element.

class Base {
  /// <param name="x">Doc for x</param>
  protected void Method1(int x) { }
}

class Derived : Base {
  /// <inheritdoc cref="Base.Method1"/>
  /// <param name="y">Doc for y</param>
  protected void Method2(int x, int y) { }
}

CS1712

Type parameter has no matching typeparam tag in the XML comment (but other type parameters do)

This is similar to the previous case, but applies for type parameters. The example shows type parameters for a generic type, but it can also apply to generic methods.

/// <typeparam name="T">Doc for T</param>
class Base<T> {
}

/// <inheritdoc/>
/// <typeparam name="T2">Doc for T2</param>
class Derived<T, T2> : Base<T> {
}

Tools

This section describes the manner (semantics) in which inheritdoc elements should be evaluated.

Will be added in a later comment

[pascalberger]

The compiler SHOULD preserve the placement and form of the inheritdoc element in the XML documentation file. It MUST NOT replace the inheritdoc element with inherited documentation when writing the documentation file.

Why shouldn't inheritdoc be replaced in the XML documentation file? This would make the generated XML documentation files usable to a much broader set of tools IMHO

[daveaglick]

I agree with @pascalberger above about replacing in the XML documentation file. There are tools, including documentation generators, that use the XML doc file as a substitute for having access to the source. If the inheritdoc comments aren't replaced in the output XML file then those tools will have to continue to implement the inheritdoc logic and we're back to where we started.

If that's not feasible, perhaps the XmlDocumentationProvider could be extended to perform the substitution. At least that way a tool/generator could read the assembly with Roslyn, hooking up the XML comment file via the provider, and get consistent inheritdoc resolution.

[sharwell]

Why shouldn't inheritdoc be replaced in the XML documentation file?

Ignoring the "it's what we do now" issue, three immediate reasons:

1. The XML documentation files might not be available at compilation time, but added later. For example, suppose X.dll 1.0 depends on Y.dll 1.0, but the latter doesn't include XML documentation. A user later builds App.exe depending on X.dll 1.0 and explicitly updates Y.dll to 1.1, which now includes documentation. The inherited documentation should propagate to methods in X.dll where inheritdoc was specified.
2. XML documentation of a base type may change, and typically users want the changes to propagate without requiring the library be recompiled. (I know in all cases where I used inheritdoc in the past, this was my expectation.)
3. Duplicating the documentation unnecessarily bloats the output XML form.

At least that way a tool/generator could read the assembly with Roslyn, hooking up the XML comment file via the provider, and get consistent inheritdoc resolution.

I would expect Roslyn to provide an API which provides code element documentation with inheritdoc expanded.

[pascalberger]

While I see the advantages you mention, another downside, beside documentation generators mentioned by @daveaglick, of this approach is that if a library is created with inheritdoc tags in the documentation XML they won't be resolved for users of older versions of Visual Studio.

[sharwell]

While I see the advantages you mention, another downside, beside documentation generators mentioned by @daveaglick, of this approach is that if a library is created with inheritdoc tags in the documentation XML they won't be resolved for users of older versions of Visual Studio.

That's a very good point. I forgot I use SHFB as a preprocessor to resolve these before packaging NuGet from projects that use inheritdoc.

🔗 tunnelvisionlabs/dotnet-threading@a253a2b

[matkoch]

Given the potential pitfalls, I'm very much against adopting the select feature. When changing the documentation in some base class, there is no easy way to verify that none of the derived types won't break (i.e., gets their documentation changed unintentionally).

[sharwell]

Given the potential pitfalls, I'm very much against adopting the select feature. When changing the documentation in some base class, there is no easy way to verify that none of the derived types won't break (i.e., gets their documentation changed unintentionally).

Do you have examples? I've only very rarely needed select, but never run into specific problems with it. However, it's presence makes it a bit easier (IMO) to explain the behavior of inheritdoc as a nested element.

[matkoch]

@sharwell you could, for instance, select the second paragraph via select, and if you later insert a paragraph between the first and the second, the inherited paragraph gets changed without noticing that.

[daveaglick]

I'll also ++ for no select. In addition to the problems @matkoch mentioned with relative positioning of content, I think it also makes the feature more complex and confusing for very little actual gain.

[sharwell]

@matkoch I've never seen someone do that. Considering that it's hard to get users to write any documentation, much less put thought into the specific content resulting from what they write, I do not anticipate any notable number of problems arising from this feature. The only thing I've ever used it for IIRC was to remove a "note to implementers" that would otherwise have been inherited. It was a strange message to otherwise be included in the documentation for a sealed method, and I was happy to have a way to remove it.

[matkoch]

@sharwell it is even used as an example in the Sandcastle documentation (select="para[last()]"). In my opinion it shouldn't be a reasoning about whether someone is actually using this or not. It's about locality, the potential defects a change can introduce and the (understandable) missing tooling. If you add a new abstract method or change some signature, you'll get a compiler error, since derived types are affected. Changing inherited documentation however would become a task of manual verification.

I also agree with @daveaglick. Too much complexity for little gain.

[matkoch]

@sharwell A compromise could be to allow only a restricted set of select expressions. Like selection by ID.

[sharwell]

Given I have had use for select, I lean in favor of having the option. However, given how rarely I've needed it, it's certainly not essential.

A compromise could be to allow only a restricted set of select expressions. Like selection by ID.

This would be bad. Given we're already in the context of XML, XPath has a specific meaning and we don't have to redefine it. If we allow the attribute but don't use XPath, we have to redefine everything and can't use an off-the-shelf XPath implementation.

[matkoch]

@sharwell I didn't mean to introduce a new syntax, but rather to allow only a subset of xpath. I.e., no last() or selection by index.

[sharwell]

@pascalberger How about this? (I only modified the main affected element; other changes way be needed elsewhere in the text for consistency if this approach is adopted.)

The compiler SHOULD emit the documentation file with inheritdoc elements replaced by their inherited content. The compiler MAY support emitting the documentation file with inheritdoc elements not replaced; in this case the compiler SHOULD preserve the placement and form of the inheritdoc element in the XML documentation file, except with the cref attribute expanded to the documentation ID of the referenced member.

[sharwell]

Tools

📝 This section defines the inheritance semantics of the inheritdoc element, as they would apply to the tools responsible for interpreting the meaning of inheritdoc. If the compiler expands inheritdoc during the production of a documentation file (e.g. #313 (comment)), then the compiler would be considered a tool for the purposes of this section.

General

The expansion of an inheritdoc element produces a XML node set which replaces the inheritdoc element.

Inheritance rules

The inheritance rules determine the element(s) from which documentation is inherited. The behavior is unspecified if a cycle exists in these elements.

The search order is defined under the Top-Level Inheritance Rules
section of inheritdoc. However, the rules for determining which elements to ignore are generalized to the following:

• The overloads element is never inherited when the select attribute is omitted. In other words, the default value for the select attribute is *[not(self::overloads)].
• If an element includes a cref attribute, it is only omitted if the matching existing element has a cref attribute that resolves to the same documentation ID is already included
• If an element includes a href attribute, it is only omitted if the matching existing element has an href attribute with an equivalent URI
• If an element includes a name, vref, and/or xref attribute, it is only omitted if the matching existing element has the corresponding attribute(s) with the same value(s)
• After observing the above, an element is omitted if an existing element (already inherited or a sibling of the inheritdoc element) has the same element name

Inline inheritdoc elements

When an inheritdoc element appears inline (as opposed to the top level), the base node from which the select query is evaluated changes to the parent element of the inheritdoc element. The path to the matching node is identified by all of the following:

• The element name
• The values of attributes of the element
• The index of the element

For example, the following inheritdoc elements are equivalent:

/// <summary>
/// <list type="number"><item></item></list>
/// <list type="bullet">
/// <item></item>
/// <item><inheritdoc/></item>
/// </list>
class WithoutSelectAttribute { }

/// <summary>
/// <list type="number"><item></item></list>
/// <list type="bullet">
/// <item></item>
/// <item><inheritdoc select="/summary[0]/list[@type='bullet'][0]/item[1]/*[not(self::overloads)]"/></item>
/// </list>
class WithSelectAttribute { }

[pascalberger]

The compiler SHOULD emit the documentation file with inheritdoc elements replaced by their inherited content. The compiler MAY support emitting the documentation file with inheritdoc elements not replaced; in this case the compiler SHOULD preserve the placement and form of the inheritdoc element in the XML documentation file, except with the cref attribute expanded to the documentation ID of the referenced member.

@sharwell Does this mean the compiler is free how it implements it (either the SHOULD or the MAY sentence)? Or that it's some kind of an option?

Otherwise LGTM

[sharwell]

Does this mean the compiler is free how it implements it (either the SHOULD or the MAY sentence)? Or that it's some kind of an option?

@pascalberger It's written with the intent of acknowledging users may want an option to control this, while also suggesting the preferred behavior in the event the compiler only implements one or the other.

[matkoch]

@sharwell I'm confused now given your recent post. Does that mean that you will keep the select feature?

[sharwell]

@matkoch I'm in favor of keeping select, but wanted to present the alternative in concrete wording for the sake of continued discussion. As mentioned in the alternative wording comment, other language including that seen in the Tools section would need to be updated to reflect the final supported behavior.

[matkoch]

Anyone got an idea how this following example should be handled?

public interface IFoo
{
  event EventHandler A;
  event EventHandler B;
}
public class Bar : IFoo
{
  /// <inheritdoc />
  public event EventHandler A, B;
}

Will it require a cref definition? And if yes, will we always allow to reference symbols, not contained in the actual inheritance chain ?

[gulshan]

Is this done?
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/inheritdoc

[saucecontrol]

Is this done?
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/inheritdoc

Yep, starting from Visual Studio 16.4

[albert-github]

Is there a reason why <inheritdoc.../> is not in the https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md yet?

[333fred]

<inheritdoc> is a compiler feature, not a language feature. It won't go in the specification because it doesn't belong there.

[333fred]

@BillWagner or @sharwell, do we have this documented somewhere?

[EWSoftware]

Unofficially it's documented in the Sandcastle XML Comments guide. It's also documented in the Microsoft Docs C# programming guide but isn't as thorough and doesn't mention the path attribute.

[albert-github]

@333fred You mentioned: it is a compiler feature. But it is in the comment and describing the some documentation, wouldn't this typically belong to the mentioned chapter in the manual? This chapter is called "Documentation comments" and it states at the first line: "C# provides a mechanism for programmers to document their code using a special comment syntax that contains XML text. "

[333fred]

But it is in the comment and describing the some documentation, wouldn't this typically belong to the mentioned chapter in the manual?

The manual you linked is the C# language specification, defined as ECMA-334. <inheritdoc> is not a C# language feature, it is a special tag that Roslyn/docfx understands. It is therefore not part of, nor will it be part of, ECMA-334, unless someone champions the feature to add it to the formal definition of the language. It may seem like me being pedantic, but it's the difference between "a 3rd party C# compiler needs to implement this feature in order to be considered a C# compiler" and "a 3rd party C# compiler might want to implement this so that existing code that works with Roslyn and docfx works with it."

[albert-github]

I linked to https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md in my first comment (#313 (comment)) and in my second comment (#313 (comment)) I made reference of the quoted which is in the mentioned link as well as in the Annex D of the:

so I would expect that the <inheritdoc> will be in the Annex D of the forthcoming standard and thus in the linked file.

I'm definitely not saying it is part of the c# language but I don't think <see> is part of the language though it is described in this Annex D.

[333fred]

I'm definitely not saying it is part of the c# language but I don't think <see> is part of the language though it is described in this Annex D.

If it is part of the spec, it is part of the language.

[albert-github]

I don't really see a difference between <see> and <inheritdoc>, must be my lack of knowledge about what is part of the C# language and what not.

[sharwell]

@albert-github The <see> element was reviewed and approved for inclusion in the language a long time ago. The <inheritdoc> element is not a <see> element, so it would need to be reviewed separately if it was to be included. Currently, neither the C# compiler nor the language specification has any knowledge of the <inheritdoc> element. If one appears in source code, it is treated as an unknown documentation element that is passed on to documentation processing tools unchanged, where they are free to either ignore it or use it.

[albert-github]

@sharwell This shines a bit of new light on the problem.

• The following is my formulation: so you are saying that <see> entered in the language in the past but that this nowadays wouldn't directly happen as <see> is also just for documentation.
• where will there be an authoritative source for documentation tags (as the <inheritdoc> is now unofficially documented by Sandcastle and Microsoft as mentioned in Add a way to inherit documentation <inheritdoc /> #313 (comment))
• having the discrepancy between the ECMA specification and the unofficial description at Sandcastle and Microsoft doesn't make it very clear to a normal user, even though in the Annex D there are some remarks about ignoring tags, like:

  A conforming C# compiler is not required to check the syntax of documentation comments; such
  comments are simply ordinary comments. A conforming compiler is permitted to do such checking,
  however.

  The documentation generator must accept and process any tag that is valid according to the rules of XML.
  The following tags provide commonly used functionality in user documentation. (Of course, other tags are
  possible.)

• what is necessary to have <inheritdoc> in the ECMA standard? Most likely Sandcastle and / or Microsoft have to start a review path for this tag (and maybe there are others unknown to me).

[poke]

The correct place to expand the documentation would probably be the XML documentation chapter on this, i.e. the following document on GitHub: https://github.com/dotnet/docs/blob/master/docs/csharp/programming-guide/xmldoc/inheritdoc.md.

[albert-github]

@poke Looks like promising, though I don't see any reference that this is a repository intended for preparing for standardization by e.g. ECMA / ISO / ...

[333fred]

though I don't see any reference that this is a repository intended for preparing for standardization by e.g. ECMA / ISO / ...

This repository is about additions to the C# language. Eventually, such changes will make their way into the ecma spec, as they are part of the language.

[albert-github]

@333fred Nearly contradicting to previous comments, but as I understand it now the <inhertitdoc> might in the future be part of the ECMA standard as part of the language, hopefully it won't take too long.

[andre-ss6]

I'm not sure if this is the right place; Sorry if it's not.

I've noticed that <inheritdoc /> now has greater priority over docs defined in the member itself. I remember this not being case a couple years back.

Eg.:

        /// <summary>a</summary>
        public void A() {}

        /// <inheritdoc cref="A()"/>
        /// <summary>b</summary>
        /// <returns>foo</returns>
        public void B() {}

The output docs for B is:

a

Returns:
foo

When I expected:

b

Returns:
foo

[CyrusNajmabadi]

tagging @sharwell . however, it's not a case where one set of docs is brought in, then overwritten by other docs. Rather, the set of docs brought in is just brought in verbatim with no processing done on it.

[ZacharyPatten]

dotnet/roslyn#54494 @andre-ss6

[geoffbon]

Is it intended that <inheritdoc /> be usable to embed inside parameter descriptions?

For example, a constructor might take values to populate the class properties, and the parameters of that constructor will have the same description as the original property.

For example:

class MyEntity
{
       /// <summary>
        /// The code of the item
        /// </summary>
        public string Code
        {
            get;
            set;
        }

       /// <summary>
        /// The description of the item
        /// </summary>
        public string Description
        {
            get;
            set;
        }

        /// <summary>
        /// Creates a new entity
        /// </summary>
        /// <param name="code"><inheritdoc cref="MyEntity.Code"/>/param>
        /// <param name="description"><inheritdoc cref="MyEntity.Description"/>/param>
        public MyEntity(string code, string description)
        {
        }
}

Currently this example inserts blank values in place of the <inheritdoc /> tag.

[ZacharyPatten]

@geoffbon

It was intended that inheritdoc copies the XML docs from the source at the same XML path as it is used on the target. However, there is a bug in it currently where it concatenates docs rather than copying the specific doc at the identical x-path.

In your case you are using inheritdoc inside the param so it would copy the content from the source that is at the same x-path (also inside param tag). However you also have malformed XML. You are missing a < on /param>.

Personally, I don't like how it functions based on x-paths by default, but it was intended.

[ZacharyPatten]

sorry I bumped the comment button earlier than intended... Here is an example that will fix your issue @geoffbon

class MyEntity
{
	/// <summary>
	/// The code of the item
	/// </summary>
	public string Code
	{
		get;
		set;
	}

	/// <summary>
	/// The description of the item
	/// </summary>
	public string Description
	{
		get;
		set;
	}

	/// <summary>
	/// Creates a new entity
	/// </summary>
	/// <param name="code"><inheritdoc cref="Code" path="/summary"/></param>
	/// <param name="description"><inheritdoc cref="Description" path="/summary"/></param>
	public MyEntity(string code, string description)
	{
	}
}

If you explicitly provide an x-path (via the path attribute on the inheritdoc tag) you can override the path used during the look up.

[geoffbon]

This is outstanding, thanks so much @ZacharyPatten! This makes a lot more sense to me now.

[Varorbc]

vs 17.4 has added the inherit doc feature, but what is the shortcut?

[binki]

@Varorbc what sort of shortcut are you looking for? If you want IntelliSense to inherit the full documentation for an interface member or abstract method, it already does that if you simply omit the documentation comment entirely.