Automated checking for unmentioned types

From what I understand, by default, all types (enums, structs, etc.) are shown in the root documentation page... unless they are specifically mentioned in some Markdown file inside the docc archive. We like how this lets us organize our documentation into sections and nested files.

Is there a way to check (in CI, so programmatically) whether there are unmentioned symbols in the archive? As in, whether there are any symbols being shown in the root of our documentation below our carefuly curated categories? Right now, I have to manually check this for every merge request as I haven't found any way to automate the process.

You've understood correctly that DocC provides a default organization for symbols and articles when the content doesn't specify an explicit organization for that page. I'm not aware of a good way to check what pages are explicitly organized and what pages are automatically given a default organization.

DocC has an experimental feature for reporting "documentation coverage" and I feel like this topic (documentation organization) could be good to discuss in that context. My thinking is that the use case for wanting to know if there are symbols (or other pages) with default organization is somewhat similar to the use case of wanting to now if there are symbols without documentation (or with partial documentation).

3 Likes

I've used the experimental coverage features for exactly this functionality. The downside is that it's not always obvious, but if you know the numbers to look for, they can be helpful. As an example from one of my libraries:

   --- Experimental coverage output enabled. ---
                | Abstract        | Curated         | Code Listing
Types           | 83% (10/12)     | 100% (12/12)    | 17% (2/12)
Members         | 96% (108/113)   | 100% (113/113)  | 1.8% (2/113)
Globals         | 18% (9/50)      | 100% (50/50)    | 0.0% (0/50)

The "abstract" percentage for types and members is all about the one-line descriptions for each type, and the curated percentage is what's been organized. If one of those curated numbers drops, then I've likely added a symbol in the code, but haven't "placed it" in the organization.

Be aware though - it's experimental (as @ronnqvist mentioned), and I've seen far more issues with it trapping out and failing when I use it with libraries that have deeper dependency trees, and that's particularly noticeable in a CI-like situation, so I'd be very wary of recommending this kind of thing as a "check" for a PR - although it's been helpful in a purely "advisory" role for me.

1 Like