“See Also” sections are, by design, an educational tool. They recommend additional pages of interest within the current context and can be incredibly useful when learning new API.
When generating a “See Also” section for a given page, Swift-DocC includes sibling pages without first considering their availability. With the above motivation in-mind, it feels counterintuitive to recommend the reader visit the page of one or more deprecated symbols. When navigating to such a page, it's likely they'll be advised of the deprecation and instructed to visit another page — a somewhat confusing experience.
Therefore, I’d like to propose the following:
- Extend the
@AutomaticSeeAlso
option directive that @ethankusters implemented in Supporting more types of documentation with Swift-DocC to accept a newnonDeprecatedSiblingPages
value. - That this new value becomes the default behavior moving forward.
With this change, Swift-DocC will continue to emit pages for deprecated symbols just as it does now, and authors can carry on linking to and organizing them; the only impact is that those pages will no longer be considered for inclusion in the “See Also” sections of their sibling pages.
Examples
@Options {
@AutomaticSeeAlso(nonDeprecatedSiblingPages)
}
This proposal is additive-only; the existing behavior of @AutomaticSeeAlso
remains unchanged.