A few recent pitches (1, 2, 3) have introduced a handful of "option directives" to Swift-DocC.
Unlike other directives—which describe page structure, on-page elements, or data for a specific page, option directives describe a configuration for a type of element, potentially across multiple pages. Because of this difference, the general directive naming convention hasn't been a good fit for option directives.
I feel that the naming convention that can be derived from the option directives so far doesn't offer strong guidance for how to add future option directives or option directive arguments and that this could cause problems with inconsistent authoring syntax in the long term.
I would personally prefer to try and deal with it now while option directives are still new and the number of directives is still low. My concern is that if we wait too long, we'll have to both rename more directives and do so when more people are using them.
Current directive names
Most non-option directives are nouns and their arguments are attributes of that noun. For example:
@Tutorial(time: 30) { ... }@ContentAndMedia(layout: horizontal) { ... }@Choice(isCorrect: false) { ... }-
@Volume(name: "Getting Started") { ... }.
Unlabeled directive arguments is a special case for when the first argument is described by the directive name. For example:
@DisplayName("Something", style: symbol)@TitleHeading("Release Notes")
In contrast, the option directives so far all use unlabeled directive argument but only the TopicsVisualStyle argument value read as being described by its directive name :
@TopicsVisualStyle(detailedGrid)@AutomaticSeeAlso(siblingPages)@AutomaticTitleHeading(pageKind)
Because the arguments are all unlabeled it's not clear to me if a new hypothetical configuration for the auto-generated "See Also" sections would best be added as a new argument to the existing directive or if it would be a new directive all together.
If it would be added as a new argument then that makes me wonder why both arguments aren't labeled. Presumably if the two arguments were added in the opposite order then which argument is labeled and unlabeled would also change.
If it would be added as a new directive then that makes me wonder what it would be called. The existing convention seem to suggest that it could be named "AutomaticSeeAlso" without an argument label but there's already an option with that directive name.
I view these questions as an indication of the type of issues we may run into with naming future option directives.
Analysis of current directive behaviors
To get a better sense of what these directives could be otherwise be named I'll describe what they do. I'll also include the not-yet-implemented @AutomaticTextCasing directive and the @AutomaticTopics future direction to have examples to work with.
@AutomaticSeeAlso
Controls what items are used to generate automatic "See Also" sections. The argument is the type of information to use to generate automatic "See Also" sections, with the possible values siblingPages (the default) and disabled .
@AutomaticTitleHeading
Controls what information is used to generate the page-title’s automatic heading. The argument is the type of information that's displayed in the generated page-title heading, with the possible values roleKind (the default) and disabled .
@TopicsVisualStyle
Controls how topic sections (both manual and auto-generated) are presented, including whether or not they're presented at all. The argument is the style itself with the possible values list , compactGrid , detailedGrid , and hidden .
@AutomaticTitleCasing
Controls the capitalization / casing style for all auto-generated text. The argument is the casing style, with the possible values title (the default) or sentence .
@AutomaticTopics
Controls the sort order that items are organized in auto-generated Topic Sections . The argument is the sort order, with the possible values alphabetical (the default) or sourceOrder .
Of the above, TopicVisualStyle and AutomaticTitleCasing are nouns where the argument is described by the directive name. Since AutomaticTitleCasing applies to all auto-generated text it would probably be better named AutomaticTextCasing .
The directive names AutomaticSeeAlso , AutomaticTitleHeading , and AutomaticTopics doesn't provide an indication as to what the argument value is. AutomaticSeeAlso and AutomaticTitleHeading are used to disable a default generated element but they use a two value enumeration (one named after the current behavior and one that's "disabled") instead of a disabled/enabled value to future-proof against new configuration values.
Suggested option directive convention
Ethan and I have been discussing a handful of alternatives for option directive naming conventions and are converging on these guidelines for naming option directives:
- When multiple configurations apply to the same user-perceived element; prefer one directive with multiple arguments over multiple single argument directives. Name the directive after the user-perceived element and label both arguments.
- When the configuration is a noun where the argument is described by the directive name, use an unlabeled argument same as for non-option directives.
- When the configuration is describing how to turn off a default behavior, name the directive after the user-perceived element that the configuration applies to and use an unlabeled enabled/disabled argument to control the on/off behavior. Use labeled arguments for additional configuration. This separation is preferred for consistency even if the on/off behavior and the other configuration can be combined.
For example; pretend that we wanted to add configurations to change both the order of auto-generated topic sections and the order of items within an auto-generated topics section. Following the first guideline, it's preferred to have a hypothetical AutomaticTopics(sectionOrder:elementOrder:) directive over having two separate AutomaticTopicsSectionOrder() and AutomaticTopicsElementOrder() directives.
Applying these guidelines to the current option directives; @TopicsVisualStyle and AutomaticTitleCasing may use an unlabeled argument because they are noun phrases where the directive name describe the argument. AutomaticSeeAlso , AutomaticTitleHeading , and AutomaticTopics would introduce a leading enabled (default)/disabled argument and label the other argument.
The most recent option directive pitch is already using this naming for the new @AutomaticSubheading directive.
Concrete changes
Applying these naming conventions to the current option directives, we propose the following concrete changes:
@AutomaticSeeAlso
The siblingPages argument value (the default) will be replaced by an enabled value (the default). In both cases this has the same behavior as not adding the directive.
The not-yet-implemented nonDeprecatedSiblingPages argument value will be replaced by a excludeDeprecatedPages value to a new behavior argument.
@AutomaticTitleHeading
The roleKind argument value (the default) will be replaced by an enabled value (the default). In both cases this has the same behavior as not adding the directive.
@TopicVisualStyle
This option directive remain unchanged.
@AutomaticTitleCasing
This not-yet-implemented option directive will be renamed to @AutomaticTextCasing but its argument remain unlabeled with the values title (the default) and sentence .
@AutomaticTopics
This future direction option directive will add an elementOrder label to its argument.