As we've been iterating on the design enhancements being made to Swift-DocC-Render along with the addition of the navigator sidebar, we've received feedback that the "No overview available" text Swift-DocC currently adds to otherwise undocumented pages feels extraneous in the new design.
I'm looking for feedback on the removal of this text moving forward.
I have a draft Swift-DocC PR up here that implements this change and there will be additional changes to Swift-DocC-Render to support this as well.
I’ve uploaded a custom version of Swift Argument Parser’s documentation to my fork (with all of the documentation comments removed) to allow for a comparison of how a largely undocumented framework would appear before and after this proposed change.
NOA is useful for indicating to readers that a symbol could have documentation, but currently doesn’t. for example, fully-autogenerated pages for things like generic parameters and extensions are planned for swift-biome, and these pages would never have manually-written documentation.
For Swift-DocC specifically, it's possible to manually write documentation for all pages. Even if a symbol doesn't technically have a source location for a documentation comment, it can be documented with a documentation extension file. So I don't think, in this case, "No overview available" provides a useful indication of that.
Oh this is interesting. I still think there is value in "no overview available" to indicate that the symbol wasn't explicitly documented, it might serve as a reminder to the product's author. However, it does make the page feel more cluttered and I think that in the end that is more important to the consumer of the documentation. Knowing that a symbol could have been documented better doesn't provide the consumer with useful actionable information and therefore is just noise. Maybe there is a better way to signal to the author that the symbol is missing explicit documentation, maybe some sort of opt-in diagnostic about "documentation coverage"?
I agree- I think that the core value "no overview available" provides is to the author and not to the reader. So we should look into a solution that provides the information to the correct audience. Cluttering the documentation page for all readers of the documentation in order to provide information that is only actionable to the framework's authors doesn't seem like something we should make a habit of.
Swift-DocC does have an experimental documentation coverage feature that emits a report of the documented/undocumented symbols in a framework and this is definitely something we should expand on to better meet this need. I really like your idea of allowing folks to opt-in to inline diagnostics if a symbol is missing docs or a function is missing parameter docs for example.
Yes, Jazzy's report on this is very helpful. Really it should be a linter setting, if Swift had an official linter, but having some kind of official tooling do it would be good.
This thread brings up the value in discussing (probably in a different thread) of features and improvements to help developers diagnose issues in their documentation at generation time. Lots of cool possibilities come to mind reading through here - thanks!
And agree, doesn't seem like we should put notes in the generated docs to provide hints to the original doc author -- that's not all that useful for the end reader.
The proposed change has been merged to Swift-DocC's main branch:
Thank you all for the great feedback here! Looking forward to continue exploring better ways to expose documentation coverage to authors of Swift-DocC docs.
