Doraku / DefaultDocumentation

Create a simple markdown documentation from the Visual Studio xml one.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Add support for documenting "visible" members

madelson opened this issue · comments

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)

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

@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; }
}

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.