Doraku / DefaultDocumentation

Create a simple markdown documentation from the Visual Studio xml one.
MIT No Attribution
157 stars 26 forks source link

Add support for documenting "visible" members #116

Closed madelson closed 1 year ago

madelson commented 2 years ago

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:

Doraku commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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.