Populate the "Possible Values" section based on OAS data

[pdwilson12]

Bug/issue #, if applicable: rdar://123262314

Summary

REST/JSON data types support defining the allowed set of values a type can take (ie, an enumerated type) using the allowedValues key. These changes add support for generating a "Possible Values" section type for documenting the individual values, using a - PossibleValues: group in markdown. The rendered values will be limited to values defined by the symbol graph and will be presented in the same order as in the allowedValues key for the symbol.

Dependencies

None

Testing

Run DocC on the DictionaryData.docc fixture within the repo. The Month symbol includes 3 enumerated values and its markdown file attempts to document 2 of them out of order along with an invalid third entry. When rendered the real 3 values should be rendered in proper order along with the documentation for 2 of them.

Steps:

1. Build docc for this branch
2. Preview DictionaryData.docc and review (and edit) the Month page.

Checklist

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

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

[pdwilson12]

@swift-ci please test

[d-ronnqvist]

I have some questions about the API design of the added public types.

Also, we should add tests that verify that diagnostics work and are associated with the content's file and source range. For example, it would be good the verify that a <doc:ThisWillNotResolve> raises a warning and highlights the right line of code when used in a "Possible Value" description.

[d-ronnqvist]

New code should capture and use the nameRange and itemRange. Otherwise diagnostics for this content can't be associated with the file where the content comes from.

It would also be good to add a test that verifies that diagnostics in the possible value content are presented with the relevant source and range information.

[d-ronnqvist]

This seems only relevant within PossibleValuesSection. Is it possible to make it a nested type instead of adding a top-level type with such a general name?

[d-ronnqvist]

Directly manipulating a string index and using it to access the content in a loop like this is a bad way of working with Strings in Swift. It's possibly accidentally quadratic because the characters are not known to be the same number of bytes.

I think this is trying to do something like the below to find the start of the next if there are multiple spaces between the colon and the word

let nameStartIndex = initialText[...colonIndex].drop(while: { $0 != " " }).dropFirst().firstIndex(where: { $0 != " " }) 
    ?? initialText.startIndex

in which case it might be more robust to use $0.isWhitespace to also handle tabs and other whitespace characters.

let nameStartIndex = initialText[...colonIndex].drop(while: { !$0.isWhitespace }).dropFirst().firstIndex(where: { !$0.isWhitespace }) 
    ?? initialText.startIndex

Regardless. It would be good to add a short comment to describe why this is happening.

[d-ronnqvist]

Can you explain why is this parameter needed? If the code scans up to the first colon then does it matter if the line looks like

- one two: Description 

or

- one: Description 

?

[d-ronnqvist]

I don't understand the structure of this type. Is there any relation between the documentedValues and definedValues? It looks to me like each documented values's value may(?) correspond to one of the defined values? If that's correct, would it be better to model this like [SymbolGraph.AnyScalar: [Markup]?] or something along those lines?

It's hard and takes a long time to change a public API after it's been added. If we aren't sure that we have the right API then we shouldn't make it public yet.