Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Basic support for top-level inheritdoc elements. #1178

Merged
merged 2 commits into from Jan 22, 2017
Merged

Conversation

@AustinWise
Copy link
Contributor

AustinWise commented Jan 14, 2017

This pull requests implements a subset of the inheritdoc functionality available in Sandcastle. Specifically, it implements most of the "Top-Level Inheritance Rules". It dose not implement:

  • Support for the cref or select attributes.
  • Automatic inheritance of documentation for explicit interface implementations.
  • Support for inline inheritdoc tags (i.e., an inheritdoc tag inside of an example tag).

In spite of these limitations, I think this still quite useful, as the most common use of these feature is to place a single <inheritdoc /> on a class method to inherit the documentation from a base class or interface.

Fixes #247.

Does not support inheritdoc elements nested inside other elements.
Does not support any attributes on inheritdoc elements.
Fixes #247.
@dnfclas
Copy link

dnfclas commented Jan 14, 2017

Hi @AustinWise, I'm your friendly neighborhood .NET Foundation Pull Request Bot (You can call me DNFBOT). Thanks for your contribution!
You've already signed the contribution license agreement. Thanks!

The agreement was validated by .NET Foundation and real humans are currently evaluating your PR.

TTYL, DNFBOT;

@pascalberger
Copy link
Contributor

pascalberger commented Jan 15, 2017

If this is considered for meging could you please also add some documentation about support for inheritdoc and the limitation mentioned in this PR description to the /docs/*.md files.

Return.CopyIneritedData(src.Return);
}

static void CopyInheritedParameterList(List<ApiParameter> dest, List<ApiParameter> src)

This comment has been minimized.

Copy link
@vicancy

vicancy Jan 16, 2017

Contributor

minor: add private access modifier as coding convention

/// </summary>
public class CopyInherited : IResolverPipeline
{
readonly List<string> mEmptyList = new List<string>();

This comment has been minimized.

Copy link
@vicancy

vicancy Jan 16, 2017

Contributor

minor: coding convention: private readonly List _emptyList = new List();

@richardschneider
Copy link
Contributor

richardschneider commented Jan 16, 2017

@@ -34,5 +34,11 @@ public class ApiParameter
[JsonProperty("attributes")]
[MergeOption(MergeOption.Ignore)]
public List<AttributeInfo> Attributes { get; set; }

public void CopyIneritedData(ApiParameter src)
{

This comment has been minimized.

Copy link
@vicancy

vicancy Jan 16, 2017

Contributor

null check for src? and also null check for other CopyInheritedData?

This comment has been minimized.

Copy link
@vicancy

vicancy Jan 16, 2017

Contributor

Typo Inerited

/// <summary>
/// Copies doc comments to items marked with 'inheritdoc' from interfaces and base classes.
/// </summary>
public class CopyInherited : IResolverPipeline

This comment has been minimized.

Copy link
@vicancy

vicancy Jan 16, 2017

Contributor

minor: convention: use the same name for file name and class name

This comment has been minimized.

Copy link
@vicancy

vicancy Jan 18, 2017

Contributor

rename FileName to CopyInherited.cs

@richardschneider
Copy link
Contributor

richardschneider commented Jan 16, 2017

@pascalberger It's a bit harsh making @AustinWise write documentation for a XML comment element. I cannot find any docfx on the currently supported elements.

@@ -34,5 +34,11 @@ public class ApiParameter
[JsonProperty("attributes")]
[MergeOption(MergeOption.Ignore)]
public List<AttributeInfo> Attributes { get; set; }

public void CopyIneritedData(ApiParameter src)

This comment has been minimized.

Copy link
@ansyral

ansyral Jan 16, 2017

Contributor

how about visitor pattern?

@superyyrrzz
Copy link
Contributor

superyyrrzz commented Jan 16, 2017

namespace Microsoft.DocAsCode.Metadata.ManagedReference

minor: add copyright above


Refers to: src/Microsoft.DocAsCode.Metadata.ManagedReference/Resolvers/CopyInheritedDocumentation.cs:1 in e1d76f5. [](commit_id = e1d76f5, deletion_comment = False)

Specifically, fix spelling mistakes and remove and unused field.
@AustinWise
Copy link
Contributor Author

AustinWise commented Jan 16, 2017

While I agree with @pascalberger that ideally that ideally this feature and its limitations should be documented, I came to the same conclusion as @richardschneider: presently the XML documentation comment syntax is not documented in this repository. So it is not obvious to me where this feature should be documented.

@vicancy vicancy merged commit a2ba6d5 into dotnet:dev Jan 22, 2017
1 check passed
1 check passed
continuous-integration/teamcity Finished TeamCity Build Docfx CI :: dev : Tests passed: 623, ignored: 2
Details
@AustinWise AustinWise deleted the AustinWise:inheritDoc branch Jan 23, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

7 participants
You can’t perform that action at this time.