Refine logic for when curation removes a symbol from automatic curation

[d-ronnqvist]

Bug/issue #, if applicable: rdar://133338975

Summary

This refines the logic for when authored curation would remove a symbol from automatic curation.

Before this, any authored curation would remove a symbol or article from automatic curation.

With these changes, a symbol isn't removed from automatic curation if it's curated outside of its canonical container.

This new code comment explains the new logic well:

For symbols we only stop automatic curation if they are curated within their canonical container's sub-hierarchy or if a top-level symbol is curated under another top-level symbol (more on that below).

For example, curating a member under an API collection within the container removes the member from automatic curation:

 ┆
 ├─SomeClass
 │ └─API Collection
 │   └─SomeClass/someMethod()  ◀︎━━ won't auto curate

However, curating a member outside under another container doesn't remove it from automatic curation:

 ┆
 ├─Other Container
 │ └─SomeClass/someMethod()  ◀︎━━  will still auto curate under `SomeClass`
 ├─SomeClass

The same applies if the authored curation location is a another member of the canonical container:

 ┆
 ├─SomeClass
 │ └─SomeClass/SomeInnerClass
 │   └─SomeClass/someMethod()  ◀︎━━ will still auto curate under `SomeClass`

Top-level symbols curated under other top-level is an exception to this rule.

 ┆
 ├─SomeClass
 │ └─OtherTopLevelClass  ◀︎━━ won't auto curate because it's top-level.

The reason for this exception is to allow developers to group top-level types under one-another without requiring an API collection. For example, in DocC one could curate DiagnosticConsumer, DiagnosticFormattingOptions, and Diagnostic under DiagnosticEngine, treating the DiagnosticEngine as the top-level topic for all diagnostic related types.

These added tests also verify when specific types curation do or don't remove a symbol from automatic curation.

Dependencies

None.

Testing

In a project with some symbols:

• Curate a top-level symbol under its module.
  • This will stop automatically curating that symbol.
• Curate a top-level symbol under an API collection under the symbol's module.
  • This will stop automatically curating that symbol.
• Curate a top-level symbol under another top-level symbol.
  • This will stop automatically curating that symbol.
• Curate a top-level symbol under a member of another symbol.
  • This won't stop automatically curating the top-level symbol.
• Curate a member of some top-level symbol under a different top-level symbol.
• This won't stop automatically curating the member symbol.
• Curate an article under a member of a container symbols.
  • This will stop automatically curating that article.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[d-ronnqvist]

@swift-ci please test

[anferbui]

Looks good to me, left some small comments.

[anferbui]

Should this be shouldAutoCurateInCanonicalLocation?

[d-ronnqvist]

Yes, thank you. I renamed that property more than once for this.

[d-ronnqvist]

Fixed in f4265d3

[anferbui]

An example here might be helpful, as I'm not sure how recognisable the term "canonical container symbol" will be for those reading this documentation.

[d-ronnqvist]

I rephrased this in f788950 to "the type that defines the member". That sentence gets a bit confusing with symbols that have different locations in different language representations but I think overall fewer people will be confused by it.

[d-ronnqvist]

@swift-ci please test