Add option to generate documentation for private classes

[sathishmscict]

In final documentation private classes , methods and properties are not visible. Rest of the all classes documentation generated properly.

[jcollins-g]

This is as designed. We could add an option to document these, however.

[natewilson]

@sathishmscict Are you referring to identifiers that begin with an underscore (_) or identifiers that are not export-ed from the library (i.e. typically used only within /lib/src)?

[welshcathy]

I'd be interested in it documenting anything in a library that is not explicitly exported as part of its API please!

[JagandeepBrar]

I'd also be interested in the ability to generate docs for all classes, including private classes.

I have a private class initialized within another class (that is exported/public) to ensure that they cannot initialize it outside of the class and so it doesn't pollute intellisense, but I'd like them to be able to read the documentation on the internal functions for that class.

[michaelu123]

In Flutter we have stateful widgets, where the public class is normally small and uninteresting, with all the logic in a State class with a private name. These State classes demand documenting!

[krushnakant-iitb]

Any updates on this? Is there any option to document private classes also?

[jcollins-g]

There is no update as yet, but since there's been continuing traffic on this feature request, elevating to P2.

[jcollins-g]

It sounds like the general trend is to desire documentation for all private library members in a library or even package.

If it is going to be at the library or package level I'd perhaps lean toward a dartdoc_options parameter listing files and/or toggling the whole package. Not very fine grained, but either of those two options would get the job done in many cases. Otherwise, a package:meta annotation -- something like @visibleInDocumentation -- would seem to be the way to go, similar to @visibleForTesting. One disadvantage of that approach is that you'd have to tag any non-public symbol with that tag for it to show up. Any thoughts?

[krushnakant-iitb]

@visibleInDocumentation seems the best bet here- as that also gives the option to document certain private members while keeping others completely private.

[michaelu123]

All of this could be done, where the more specific overrules the more general. In the flutter case, I would like to document my own packages, and not all packages, thus the package level would suit me.

[jcollins-g]

Since annotations can be present on libraries, if we do both probably the dartdoc_options version would be limited to entire packages or directory trees.

This would also be a good time to deprecate the archaic @nodoc dartdoc directive that has to be embedded with documentation comments and replace that with another annotation.

[eyalkutz]

The option to include private classes (_Foo) is important for documenting flutter apps because otherwise, you cannot document StatefulWidgets

[serendipity1004]

yes it would be great if we could document statefulwidgets too. If anyone can point to where private class logging can be enabled, I would like to create a fork and use that meanwhile

[amarghosh]

This would be nice to have please.

[Levi-Lesches]

Another use-case: I use documentation mostly for my team when I'm writing apps, since the users are probably never going to see the API docs. So I want my team to be able to see everything -- private and non-exported classes still have to be maintained! Using the generated website's search bar is much easier than scrolling through files and guessing where the class you're looking for may be, then having to search within that file for what you're looking for. Having an option that documents literally everything (in my own project, not all my imports), would fix this.

[srawlins]

That's a solid use case. In many cases, docs are for authors of the code, not clients of the code. For example, every flutter app ever 😛.

[szepetry]

Any updates on this?

[gaetgu]

Anything new on this? I would really like to be able to have this feature. I agree with srawlins that docs are most generally used for authors, rather than the clients, and it would be really nice to see the definition of all of my private methods.

[zathras]

Just to flesh out a use case: Running dartdoc on private classes would be really nice when people use the state pattern. Navigating around a deep inheritance tree isn't very well supported in the Dart ecosystem. Dartdoc of private classes provides a quick path to get there, especially via the "Implementers" link.

[srawlins]

No change on prioritization here. This is still a P2 enhancement, and we don't currently have time scheduled to implement it.

[Levi-Lesches]

@jcollins-g @srawlins, I'd like to take this up. I have made good progress on my local build of the dartdoc package (using that to test instead of dart doc because it's easier to run a package than rebuild the Dart SDK). I plan on submitting a PR soon. Is there anything I should watch out for?

My current implementation starts with a config option private-members passed as either a command-line argument or through dartdoc_options.yaml (ie, a DartdocOptionArgFile). Then, almost every instance of Privacy.isPublic is ignored if private-members is true. This includes vital places like filterNonPublic, Documentable.isDocumented, and Canonicalization.isCanonical, which ultimately decide whether to document a member or even link to it.

Right now, my implementation only has three problems:

1. An actual implementation of the private-members option. Saving that for when I get private members working.
2. A bug where src libraries exported under lib are treated as separate libraries. For example, if I have a library lib/utils.dart that exports a class A in lib/src/utils/a.dart, dartdoc generates a separate library called a, with the URL src_utils_a/A-class.html. Even if A is not actually exported, this still happens.
3. A bug where private members inherited from another library are still being documented. For example, Flutter State objects document members such as _element and _widget, leading to 404 pages on https://api.flutter.dev.

[srawlins]

Is there anything I should watch out for?

The only things I can think of are:

• It should be behind an option.
• The option should be specifiable in dartdoc_options.yaml.
• I think it should produce documentation for the following "new" things:
  • libraries in the implementation directory (lib/src/)
  • public and private library elements (classes, ...) in the implementation directory (lib/src/)
  • private elements in public libraries (lib/)
  • private class (and mixin and extension and enum) elements on public and private classes, mixins, extensions, enums.
• I think it should not produce documentation in any directories outside of lib/.

A bug where src libraries exported under lib are treated as separate libraries.

Hmm, what does dartdoc do today for public libraries in this situation? For example, if class A is declared in lib/src/a.dart, and exported in lib/b.dart and lib/c.dart? I imagine A is listed twice? But I don't think two -class.html files should be generated...

[jcollins-g]

A bug where src libraries exported under lib are treated as separate libraries.

Hmm, what does dartdoc do today for public libraries in this situation? For example, if class A is declared in lib/src/a.dart, and exported in lib/b.dart and lib/c.dart? I imagine A is listed twice? But I don't think two -class.html files should be generated...

I would expect the same thing to happen here as happens if one public library reexports another public library -- members of both will be subject to dartdoc canonicalization and a single version of the member's doc will be referenced in both libraries.

In any implementation for this, we have to consider whether we're making more private things public, or creating a new sort of thing where private things are allowed to be documented. Which you do depends on the problem you're trying to solve -- if you still want the classes treated as private for canonicalization it will matter which direction you go. There may also be some assumptions in the code that private elements can not be canonical and/or documented, I'd watch for that.

[Levi-Lesches]

@srawlins

1. libraries in the implementation directory (lib/src/)

Do you mean the lib/src libraries should be counted as separate libraries in the left-hand sidebar? That makes sense, considering they may include a library declaration with some doc comments... I considered this to be a bug, but I guess I should rethink that. Then there's the question of where to link to them, especially if they share the same filename.

Consider lib/src/data/a.dart and lib/src/utils/a.dart. At least they will have unique library names and URLs, or dartdoc will reject them (the autogenerated name if you don't have a library declaration will suffice). Where should each library be linked? If they were on the left-hand sidebar, there would be two libraries with the same name (not to mention you'd essentially have one entry for every file in your project). Should they be nested somehow? Should implementation libraries be search-only? I'm not sure how this will work, but I am open to suggestions.

EDIT Here is an example where i made two libraries, lib/src/data/temp.dart and lib/src/services/temp.dart. I can explicitly name them or let Dart do it for me (albeit without any library docs). Here's what happens:

Without explicit library	With explicit library

In either case, the list of libraries gets rather large... I think it is enough for the members of the implementation libraries to appear in the public libraries and omit the implementation libraries themselves from the sidebar. They can still be searched or linked to members within them, though.

2. public and private library elements (classes, ...) in the implementation directory (lib/src/)

Not tested yet, but that's next on my list. It's especially helpful for Flutter, where most State objects (like _HomePageState) are private and in an implementation file.

3. private elements in public libraries (lib/)

Assuming you mean something like a private class _A in lib/a.dart -- haven't tested this yet.

4. private class (and mixin and extension and enum) elements on public and private classes, mixins, extensions, enums.

This is working. I have a public class in lib/a.dart with private members that are being documented. They're included in the properties, methods, and constructor lists and are linked to.

I may update this comment with my progress if I get some soon.
EDIT 1: Showing pictures of what happens with duplicate implementation libraries.

[Levi-Lesches]

@jcollins-g:

In any implementation for this, we have to consider whether we're making more private things public, or creating a new sort of thing where private things are allowed to be documented.

Definitely the latter. I don't want to change the meaning of the code itself, but rather expose all possible members to documentation so a team can read through their own API without opening the code. Also because the pages dartdocs generates are really nice to look at. Honestly, my favorite part of using a new package is going through their dartdocs to understand the API.

There may also be some assumptions in the code that private elements can not be canonical and/or documented, I'd watch for that.

Yeah, I'm having a lot of "fun" figuring out which isDocumented getter will actually document the private member, and which will throw a few errors. Right now I'm limited to only a few changes which I'm carefully monitoring in Git so I'll be able to figure out really drives things. I did have to make one such change -- the logic of left vs right arrows for getters vs setters relies on checking which ones are private vs public, so I had to come up with a new interpretation for private members. Fun stuff.

[srawlins]

Do you mean the lib/src libraries should be counted as separate libraries in the left-hand sidebar?

Yeah.

Consider lib/src/data/a.dart and lib/src/utils/a.dart.

I'd say we do the same things we do for libraries lib/data/a.dart and lib/utils/a.dart. Does the src/ add new questions?

[srawlins]

I think it is enough for the members of the implementation libraries to appear in the public libraries and omit the implementation libraries themselves from the sidebar. They can still be searched or linked to members within them, though.

What if they're not part of a public library? What if some elements are part of a public library, and some are not? What if some elements are part of multiple public libraries? What if some elements are part of one public library, and others are part of another? I think the simplest and least surprising choice is to document each library in src/ in its entirety.

[Levi-Lesches]

I'm seeing two options:

One, do what's currently done for non-src directories in lib (which, to be honest, I didn't even consider). This may result in duplicate sidebar entries, although the URLs have no problem. With explicit library names, the sidebar entries are unique.

Two, reduce clutter in the sidebar by omitting src libraries. These libraries and their members would still be fully documented -- the members would be linked anywhere they're referenced, and the libraries would still have their own pages, which you could get to via the breadcrumbs at the top of the page. You'd still be able to search both. the only change would be not including it in the sidebar with the other public libraries.

Does the src/ add new questions?

I think this can be justified because src libraries contain everything, so while any other option may look reasonable today, the sidebar would be extremely long if every file in the project had its own line. If the sidebar is meant to be a quick glance of your project's entry point libraries (like Flutter's material and foundation), this option would make sense.

Or, we could leave this to another config option, privateLibrariesInSidebar, which can't really hurt.

[Levi-Lesches]

FYI I'll be tracking my progress and asking future questions in #3096