Add a way to inherit documentation <inheritdoc />

[gafter]

Champion issue: #8985

(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.

[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.