Allow documentation extensions to omit module name when there's only one module

[d-ronnqvist]

Feature Name

Module-level resolution for documentation extensions

Description

Documentation extension files are markdown files that extend/continue the in-source documentation of symbols. To associate the documentation extension file with the symbol, the documentation extension file starts with a heading with an absolute symbol link to the symbol.

Because documentation catalogs are almost always associated with a single module, this means that every documentation extension repeats the same module name in its heading. When the documentation build covers a single module, it would be nice to be able to omit the module name in these documentation extension headings.

However, it's still important that modules that also have a top-level symbol with the same name as the module can create documentation extension files for both the module itself and the top-level symbol.

There are two main possibilities that I can see for handling this ambiguity:

• Require an absolute path for the symbol with the same name as the module
• Require that the ambiguous module reference starts with a leading slash.

rdar://76252171

Motivation

When using DocC to document a module, being able to omit the module name in the documentation extension headings is a small improvement to the user experience of writing documentation extensions. For some developers who are new to DocC it may be more natural to start with the name of the symbol, not the name of the module that contains the symbol.

Importance

This is a small and fairly low priority change.

Alternatives Considered

The main alternatives to consider is how to handle the new possible ambiguity if a module has a top-level symbol with the same name as the module. For example; the Something module would have a Something class or struct.

Today, the absolute links to these would be Something and Something/Something.

A simple solution to this problem is to not allow the relative link to the symbol if it has the same name as the module. In other words; the developer would still need to write Something/Something to reference the symbol but could write SomethingElse for another symbol in the same module. This has the benefit that it is fully backwards compatible.

An alternative solution would be to require a leading slash for the module name reference if it collides with a symbol. This is consistent with how a leading slash result in an absolute symbol link lookup in other places, but it's a rarely used feature. The biggest benefit for this is that the link Something would change from referring to the module to referring to the top-level symbol instead.

[d-ronnqvist]

I'm tagging this as a "good first issue" even though it's more of a good second or third issue. This mainly involved changes to link resolution and some new diagnostics. I'm happy to go into more detail if anyone is interested in this issue.

[d-ronnqvist]

the work I’m doing for #561 will also resolve this.

[d-ronnqvist]

This change caused some regression when a module and a top-level symbol had the same name. I make a targeted revert and work to reenable this again once those issues are sorted out.