Docfx: How to include a (C#) internal class?

[dougclutter]

DocFX Version Used: 2.33.0

Template used: default

Steps to Reproduce:

1. I have an internal class that I would like to include in the API docs
2. Added "include" to filterConfig.yml (details below)

Expected Behavior:
The filterConfig.yml is referenced in the docfx.json file. We know this is working because we are excluding some classes.

Added the following to filterConfig.yml:

- include:
    uidRegex: ^My\.Internal\.ClassName$
    type: Class

Expected the class My.Internal.ClassName to be included in the API docs.

Actual Behavior:
My.Internal.ClassName is not included in the API docs.

[vwxyzh]

@dougclutter removing internal classes/members is hard code logic in default filter.

[dougclutter]

@vwxyzh Thanks for the information. Short of building a custom version of docfx, is there any way to work around this?

[vicancy]

Hi @dougclutter could you help us to understand your scenario? why you'd like internal classes included? And why do customer want to see internal classes?

[Still34]

While I think internal should rarely be exposed into a public API documentation, sometimes if the XML docs refers to something that's internal, that should probably be addressed. Either by showing the docs that's not shown publicly in the API list or transforming the type into a normal string.

[dougclutter]

Hi @vicancy one of the things that we've decided to do is make our Entity Framework DbContext classes internal. We do this because we don't want programmers working on the UI or API to be able to create arbitrary queries against the database. However, we're constantly creating business objects that use the DbContext, so we'd like to include it in our docs.

Unlike many of your users, we are generating docs for our internal development team rather than the general public. Hope this helps!

[vwxyzh]

@dougclutter so do you want all of internal classes can be documented?

[dougclutter]

@vwxyzh Yes. I'd like to be able to:

1. Include specific internal classes that I specify in the filters
2. Include specific private properties/methods that I specify in the filters

[dougclutter]

@vicancy Can this be considered a feature-request now?

[murt]

could you help us to understand your scenario?

I can also add a use case to this that will become more prevalent in the future as more game engines integrate the CLI and languages beyond C# become supported.

Unity3D provide a means of connecting editor components to publicly accessible members, however they also support private members via the <SerializeField> attribute.

This works okay for C# and in all honesty public should probably be used for these values (and thus not be an issue with docfx) however F# works a bit differently - we are forced to use let mutable which is "private"

The following are equivalent:

class Foo : MonoBehaviour {
     [<SerializeField>]
     private float bar = 42.0f
}

type Foo () =
    inherit MonoBehaviour()

   [<SerializeField>]
   let mutable bar = 42.0f

It would be great if I could filter to include private members or even filter for particular attributes (as I am only likely to want to document members with <SerializeField> anyways)

[vwxyzh]

@dougclutter add --disableDefaultFilter in metadata command line options, it won't filter any API by visibility, but it still filter some API, for example APIs in root namespace.
It will release in v2.38

[jchristin]

FYI disableDefaultFilter is already working in v2.37.2 if you add it to docfx.json. A bug is preventing it to work through metadata command line options (see #3147).

[herohua]

Thank you @jchristin to help us fix #3147. The fix will be released in v2.37.3.

[jchristin]

My pleasure.

[herohua]

3147 released in v2.38.

[dougclutter]

@vwxyzh - I tried adding _disableDefaultFilter: true to the docfx.json in the build.globalMetadata section, but it doesn't appear to do anything. Am I setting it in the right place?

[dougclutter]

@vwxyzh - I'm also not sure how the DisableDefaultFilter gets me where I want to be. It seems that disabling the default filter would include all the internal classes; that's definitely not what I want. I want to be able to select specific internal classes.

[dougclutter]

I looked at the code for default filter and it appears we could resolve this by changing the default to call a function that checks to see if the current class/method/property is specifically included via filterConfig.yml. Is there an existing method that could do that?

[superyyrrzz]

@dougclutter You should set it in metadata config, e.g.

{
  "metadata": [
    {
      "src": [
        {
          "files": [ "**.csproj" ],
          "exclude": [ "**/bin/**", "**/obj/**" ],
          "src": "../src"
        }
      ],
      "dest": "obj/temp/docfxapi",
      "disableDefaultFilter": true
    }
  ],
  "build": ...
}

and API filter should be the feature you are looking for.

[crcrewso]

One reason I see for building documentation including internal and private classes/methods is for documentation.

I'm required to produce static documentation aligning to versions, at various points, for future codebase maintenance. I would very much like to use the Docfx to produce this document without having to make everything public.