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

Conversation

Projects
None yet
7 participants
@AustinWise
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.

Basic support for top-level inheritdoc elements.
Does not support inheritdoc elements nested inside other elements.
Does not support any attributes on inheritdoc elements.
Fixes #247.
@dnfclas

This comment has been minimized.

Show comment
Hide comment
@dnfclas

dnfclas 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;

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

This comment has been minimized.

Show comment
Hide comment
@pascalberger

pascalberger Jan 15, 2017

Contributor

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.

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.

Show outdated Hide outdated src/Microsoft.DocAsCode.Metadata.ManagedReference/Models/SyntaxDetail.cs
Return.CopyIneritedData(src.Return);
}
static void CopyInheritedParameterList(List<ApiParameter> dest, List<ApiParameter> src)

This comment has been minimized.

@vicancy

vicancy Jan 16, 2017

Contributor

minor: add private access modifier as coding convention

@vicancy

vicancy Jan 16, 2017

Contributor

minor: add private access modifier as coding convention

Show outdated Hide outdated ...AsCode.Metadata.ManagedReference/Resolvers/CopyInheritedDocumentation.cs
/// </summary>
public class CopyInherited : IResolverPipeline
{
readonly List<string> mEmptyList = new List<string>();

This comment has been minimized.

@vicancy

vicancy Jan 16, 2017

Contributor

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

@vicancy

vicancy Jan 16, 2017

Contributor

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

@richardschneider

This comment has been minimized.

Show comment
Hide comment
@richardschneider

richardschneider Jan 16, 2017

Contributor
Contributor

richardschneider commented Jan 16, 2017

Show outdated Hide outdated src/Microsoft.DocAsCode.DataContracts.ManagedReference/ApiParameter.cs
@@ -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.

@vicancy

vicancy Jan 16, 2017

Contributor

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

@vicancy

vicancy Jan 16, 2017

Contributor

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

This comment has been minimized.

@vicancy

vicancy Jan 16, 2017

Contributor

Typo Inerited

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

@vicancy

vicancy Jan 16, 2017

Contributor

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

@vicancy

vicancy Jan 16, 2017

Contributor

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

This comment has been minimized.

@vicancy

vicancy Jan 18, 2017

Contributor

rename FileName to CopyInherited.cs

@vicancy

vicancy Jan 18, 2017

Contributor

rename FileName to CopyInherited.cs

@richardschneider

This comment has been minimized.

Show comment
Hide comment
@richardschneider

richardschneider Jan 16, 2017

Contributor

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

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.

Show outdated Hide outdated src/Microsoft.DocAsCode.DataContracts.ManagedReference/ApiParameter.cs
@@ -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.

@ansyral

ansyral Jan 16, 2017

Contributor

how about visitor pattern?

@ansyral

ansyral Jan 16, 2017

Contributor

how about visitor pattern?

@superyyrrzz

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Jan 16, 2017

Collaborator

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)

Collaborator

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)

Address code review feedback.
Specifically, fix spelling mistakes and remove and unused field.
@AustinWise

This comment has been minimized.

Show comment
Hide comment
@AustinWise

AustinWise Jan 16, 2017

Contributor

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.

Contributor

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

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