Ooh - very interesting! Thank you for the Xcode build notes!
Is there a path to getting to that structured JSON file from DocC directly on the command line? In particular, if the project (library/framework) I'm working for a server-side library, then Xcode isn't my immediate build environment, but I'd still like to get the structured/delimited report from my CI systems.
The synopsis information (e.g. 'brief' output) groups into 3 sections: 'Globals', 'Types', and 'Members' - and its not immediately obvious which symbol types fall into which category. As the feature moves forward out of experimental status, it would be nice to have this detailed somewhere.
As it stands, the synopsis numbers are super useful (even if I was confused about some of what it was telling me - I wasn't entirely certain where it was telling me about gaps), and I absolutely love the explicit metric of "code snippet" coverage. I had a self-goal of providing code snippets for all the major classes, and it's already helped me get a view of what's there from a first rush through, and what's still pending. This is also where the detailed (structured) report comes in exceptionally handy - right now I'm manually pasting that file into a spreadsheet and filtering down to the "important" symbols - so I'd love a way to take that raw structured report output and more easily get to a filtered set based on the framework design.
Finally, I wasn't sure how (or if) Articles were exposed in this. I suspected they might be 'Globals', and in my initial case here, I have an article in the docc with a quick overview of the key ways to use the framework (the kind of stuff that had previously been dropped in the repo's README to show off the framework). However, I'm not sure that's showing that the article has a code listing.
The article is included within the larger report set when run at 'detailed' - and has several code listings within it - but it doesn't track into the 'brief' (or I didn't know how to spot it in there).