Removing deprecated symbols from auto-generated “See Also” sections

“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:

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.

5 Likes

Do we expect to introduce additional see also options? If so, this won't scale. I wonder if we should do something like @AutomaticSeeAlso(<style>, includeDeprecatedSymbols: <bool>).

On the other hand, that introduces invalid cases like @AutomaticSeeAlso(hidden, includeDeprecatedSymbols: true) but we could catch that with diagnostics.

If we don't expect to introduce additional see also options then your proposed syntax looks fine to me.

Edit: Also I think we should make this (no deprecated symbols in see alsos) the default behavior.

1 Like

I think making this the default behavior and allowing to opt-out would make more sense then requiring to opt-in considering the motivations.

100% agree with @jack and @Lancelotbronner about this becoming the default behavior and have updated the proposal to reflect that.

2 Likes