Update option directive naming

[d-ronnqvist]

Bug/issue #, if applicable:

Summary

This updates the current option directives to follow the naming convention that's proposed in this forum post.

Dependencies

n/a

Testing

Use the AutomaticArticleSubheading, AutomaticSeeAlso, and AutomaticTitleHeading option directives in content.

• The syntax for disabling the default behaviors should remain the same as before.
• The syntax for redundantly enabling these features now use an explicit "enabled" value.

Checklist

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

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

[d-ronnqvist]

@swift-ci please test

[ethan-kusters]

I can definitely be convinced that Enabledness is the best word here – I'm mostly worried about it from a documentation perspective for folks less familiar with English... Just to offer an alternative – what do you think of state: State? It's in a state of enabled or disabled.

[d-ronnqvist]

I also couldn't think a good word here. What I really want it to describe is a Bool value that can be created with "enabled"/"disabled" instead of "true"/"false" so that the directive can be written as @Directive(disabled) instead of @Directive(enabled: false).

After thinking about this some more I decided to add a new initializer to the property wrapper that allows for a Bool value with custom true/false spellings. That way we don't need to define a custom type for it however we also don't get to document the meaning of the values but it should be clear enough with a var enabled: Bool property what the two values are.

Updated in e450d41

[ethan-kusters]

Would we expect the declaration in documentation for this to be:

@Directive(_ enabled: Bool)

then?

I'm worried that will be more confusing since other instances of Bool in declarations accept true false as arguments. The documentation for the allowed values will help but it will make the declaration potentially less clear.

[d-ronnqvist]

would it help if this also supported true and false as arguments?

[ethan-kusters]

I don't think so... I'm just more concerned about the user-facing Directive documentation than the API framework documentation. For the Directive itself – using something like Enabledness or State is probably better than Bool since it indicates that this is a different thing than: https://ethan-kusters.github.io/swift-docc/documentation/docc/choice

[d-ronnqvist]

I'm not sure what the right internal API is for this. I think that the code should expose a Bool value—but that could be done with a computed property—but the user-facing Directive documentation should show something more specific than Bool.

For the type name to surface in the directive documentation I prefer Enabledness over State. To me "state" implies the computed runtime value (which may change) as opposed to a user configuration. Also, "state" is unnecessarily broad and could have more states than enabled/disabled. Even if it's the first time the developer sees the word "enabledness" it should be fairly easy to discard what it is and what it's possible values are.

[d-ronnqvist]

I'll revert back to an Enabledness enum but will surface a computed Bool value to the internal API.

[ethan-kusters]

That sounds good to me. Thank you!

[d-ronnqvist]

Ok. I've updated this to use an "enabledness" enum again and have regenerated the directives symbol graph file.

[ethan-kusters]

Looks great! Thank you.

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test