# Naming convention for DocC @Option directives

**URL:** <https://forums.swift.org/t/naming-convention-for-docc-option-directives/61713>\
**Category:** Swift-DocC\
**Tags:** docc\
**Created:** [November 30, 2022, 4:47pm UTC](https://forums.swift.org/t/naming-convention-for-docc-option-directives/61713 "2022-11-30T16:47:55Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![ronnqvist](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ronnqvist/32/20110_2.png) [@ronnqvist](https://forums.swift.org/u/ronnqvist)\
**Post date:** [November 30, 2022, 4:47pm UTC](https://forums.swift.org/t/naming-convention-for-docc-option-directives/61713/1 "2022-11-30T16:47:55Z")

</div>

A few recent pitches ([1](https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725), [2](https://forums.swift.org/t/removing-deprecated-symbols-from-auto-generated-see-also-sections/61140), [3](https://forums.swift.org/t/supporting-different-casing-styles-in-auto-generated-text/60646)) 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](https://forums.swift.org/t/customizing-the-auto-generated-overview-heading-in-swift-docc-articles/61390) 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.

---

<div class="post-metadata">

**Author:** ![chuckdude](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/chuckdude/32/27639_2.png) [@chuckdude](https://forums.swift.org/u/chuckdude)\
**Post date:** [December 1, 2022, 1:13am UTC](https://forums.swift.org/t/naming-convention-for-docc-option-directives/61713/2 "2022-12-01T01:13:27Z")

</div>

Do we need to spell out `Automatic*`? Could these be shortened to `AutoTitleCase` or `AutoTopics`?

---

<div class="post-metadata">

**Author:** ![ronnqvist](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ronnqvist/32/20110_2.png) [@ronnqvist](https://forums.swift.org/u/ronnqvist)\
**Post date:** [December 1, 2022, 6:36pm UTC](https://forums.swift.org/t/naming-convention-for-docc-option-directives/61713/3 "2022-12-01T18:36:41Z")

</div>

> [@chuckdude](#):
>
> Do we need to spell out `Automatic*`? Could these be shortened to `AutoTitleCase` or `AutoTopics`?

The guideline that we're suggesting is for the directive name to refer to the user-perceived element.

For the reasons below I personally prefer "Automatic" for its clarity.

* * *

For me personally, "auto" and "automatic" doesn't read as the same. That may just be my personal experience but since it's mostly based on symbols in UIKit and AppKit some of it may still apply to other developers who come from these platforms.

I read "AutomaticTopics" as the automatic topic sections because my instinct is to interpret "Topics" as a noun but it takes me a second to understand "AutoTopics" because my instinct is to try and interpret "Topics" as a verb. For me, this mostly comes from names used in names used in UIKit, Foundation, and AppKit frameworks where "automatic" is often used before a noun:

- [`UICollectionViewLayoutAutomaticDimension`](https://developer.apple.com/documentation/uikit/uicollectionviewlayoutautomaticdimension?language=objc)
- [`UIListSeparatorAutomaticInsets`](https://developer.apple.com/documentation/uikit/uilistseparatorautomaticinsets?language=objc)
- [`disablesAutomaticKeyboardDismissal`](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621385-disablesautomatickeyboarddismiss)
- [`toggleAutomaticLinkDetection(_:)`](https://developer.apple.com/documentation/appkit/nstextview/1449353-toggleautomaticlinkdetection)
- [`allowsAutomaticLocalization`](https://developer.apple.com/documentation/uikit/uikeycommand/3783575-allowsautomaticlocalization)
- [`allowsAutomaticMirroring`](https://developer.apple.com/documentation/uikit/uikeycommand/3783576-allowsautomaticmirroring)
- [`automaticSize`](https://developer.apple.com/documentation/uikit/uicollectionviewflowlayout/1779556-automaticsize)
- [`enableAutomaticTermination(_:)`](https://developer.apple.com/documentation/foundation/processinfo/1409422-enableautomatictermination)

and "auto" is often used before a verb:

- [`autoconnect()`](https://developer.apple.com/documentation/foundation/timer/timerpublisher/3329490-autoconnect)
- [`autoHidesToolbarInFullScreen`](https://developer.apple.com/documentation/uikit/uititlebar/3375822-autohidestoolbarinfullscreen)
- [`isVideoAutoplayEnabled`](https://developer.apple.com/documentation/uikit/uiaccessibility/3238036-isvideoautoplayenabled)
- [`autorepeat`](https://developer.apple.com/documentation/uikit/uistepper/1624079-autorepeat)
- [`autoreverses`](https://developer.apple.com/documentation/quartzcore/camediatiming/1427645-autoreverses)
- [`autosave(completionHandler:)`](https://developer.apple.com/documentation/uikit/uidocument/1619981-autosave)
- [`autoscroll(with:)`](https://developer.apple.com/documentation/appkit/nsview/1483471-autoscroll)
- [`volumeIsAutomounted`](https://developer.apple.com/documentation/foundation/urlresourcevalues/1780149-volumeisautomounted)

Even though the verb in the "auto" phrases are not capitalized it's still the pattern that my brain goes or with symbols named "auto".

---

<div class="post-metadata">

**Author:** ![ronnqvist](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ronnqvist/32/20110_2.png) [@ronnqvist](https://forums.swift.org/u/ronnqvist)\
**Post date:** [January 4, 2023, 10:49pm UTC](https://forums.swift.org/t/naming-convention-for-docc-option-directives/61713/4 "2023-01-04T22:49:11Z")

</div>

I've opened a PR that makes these suggested changes to the currently implemented option directives in [Update option directive naming by d-ronnqvist · Pull Request #448 · apple/swift-docc · GitHub](https://github.com/apple/swift-docc/pull/448).

---

<div class="post-metadata">

**Author:** ![ronnqvist](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ronnqvist/32/20110_2.png) [@ronnqvist](https://forums.swift.org/u/ronnqvist)\
**Post date:** [January 23, 2023, 10:44pm UTC](https://forums.swift.org/t/naming-convention-for-docc-option-directives/61713/5 "2023-01-23T22:44:07Z")

</div>

These changes are merged now and cherry-picked to Swift 5.8.