1

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

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
3

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

4

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

2 Likes