Warn when the documentation contains more than one root page

[d-ronnqvist]

Feature Name

Warn when the documentation contains more than one root page

Description

Today, DocC assumes that the inputs are well formed and only contain a single root page. This is true when using DocC through an integration like the Swift DocC Plugin but if developer call docc convert directly with custom inputs it's possible to pass unexpected inputs that may have unexpected behaviors.

DocC's internal logic checks that the inputs only contains a single root before performing some operations but it never surfaces this information to the developer.

Since this is unexpected input, it would be good if DocC warned when it detected such inputs.

Specifically, there are two possible situations that are worth warning about separately:

• The documentation inputs contain symbol graphs for more than one main module.
• The documentation inputs contain more than one root page. This could either happen if the developer defined a @TechnologyRoot for a catalog with symbol information (which would already have a root page for the module page), or if the developer defined more than one @TechnologyRoot.

For the first case there isn't really a source location to associate this warning with. For the second case, it would be nice if the warning was associated with the markup for the extra @TechnologyRoot directive.

Motivation

Having warnings about unexpected inputs would help developers notice issues and correct the inputs they are passing to DocC or other misconfigurations in their projects.

Importance

This is a rather low importance enhancement that's only really relevant to developers who call docc convert directly rather than through an existing integration. That said, developers who don't use DocC through a higher level integration have more reason to be notified about unexpected inputs because the inputs are in their control.

Alternatives Considered

No response