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

Add support for documenting "visible" members #116

Closed
madelson opened this issue Jul 28, 2022 · 3 comments
Closed

Add support for documenting "visible" members #116

madelson opened this issue Jul 28, 2022 · 3 comments

Comments

@madelson
Copy link
Contributor

Currently the docs say that you can filter inclusion based on modifier (public, private, etc). However, for documenting a library what I want to document is anything "visible" as part of the public API. That includes:

  • Anything public at the top level
  • Any public member on a visible type
  • Any protected or protected internal member on a publicly-inheritable type (a type is inheritable if it is visible and not sealed, has a public, protected, or protected internal constructor, and does not have any non-visible abstract members)
@Doraku
Copy link
Owner

Doraku commented Jul 28, 2022

That would basically be those values then Public,Protected,ProtectedInternal. If you have a private type with public members and use this config they will not be shown (if the parent is not shown, we can't show the children either whatever their visibility).
For ease I could create an alias for the GeneratedAccessModifiers setting that is the same as those 3 values (like Types or Members in the GeneratedPages setting).

@madelson
Copy link
Contributor Author

madelson commented Jul 29, 2022

@Doraku good to know that the parent scopes the visibility. That covers the use-case 99% which should be fine for me. I think it would be nice to have a single setting for documenting APIs (perhaps called Apis) since this seems like a common setting to use for this kind of tool.

In terms of the last 1%, here's an example:

public abstract class MyClass
{
    protected MyClass() { }

    protected int A { get; } // this is part of the public API, because someone can derive from MyClass and use this
}

public abstract class MyClass2
{
    // internal constructor prevents external inheritance
    internal MyClass2() { }

    // This is NOT part of the public API; no one outside of the assembly can call this (although
    // I suppose it could be exposed if another type in this assembly derives from MyClass and
    // offers an inheritable constructor so detecting this robustly could be complicated...)
    protected int A { get; }
}

@Doraku
Copy link
Owner

Doraku commented Jul 29, 2022

That's more a 0.01% x) but ok I understand now. For this particular case you could use exclude, it's manual but as you said it could quickly become complicated if we tried to deduce a relative accessibility based on that.

@Doraku Doraku closed this as completed in 7689ddf Feb 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants