1

as DocC is starting to enter the documentation generation space, i think it would help interoperability with Biome, Jazzy, and other peoples’ tooling if we formalized an @version markdown block directive, which could be applied to articles, tutorials, and doccomments. this would make it easier to migrate projects between documentation engines, and support multiple documentation engines, since you don’t have to switch everything at once which would fail the documentation generator CI.

since argument text is opaque to swift-markdown, each tool could define its own @version descriptor. tools that support multiple documentation dialects could also detect other tools’ descriptors, and enable appropriate compatibility features.

@version(docc: 0.1)
@version(entrapta: 0.3)
@version(jazzy: 0.14)
...

because SymbolGraphGen emits source location information for doccomments, it would not be necessary to use the @version directive on every doccomment; it could be applied on a file- or even directory-wise basis.

2

I don't think this is necessary or sufficient to do what you're looking for. Conceptually, I'm not sure I understand how a version directive would help in this scenario:

this would make it easier to migrate projects between documentation engines, and support multiple documentation engines, since you don’t have to switch everything at once which would fail the documentation generator CI.

Would you expect a documentation tool that does not have compatibility for a particular other tool to just skip the symbol? I don't think that's an acceptable result for this scenario where you want to incrementally ship.

As for the block directive itself: Documentation tools that consume Swift doc comments should ideally support Swift documentation markup syntax as a baseline to enable interoperability. But there's no requirement to do so; a documentation tool could use HeaderDoc syntax for example, and HeaderDoc's @tag <param> syntax conflicts with block directive syntax. This would also break documentation for tools like Jazzy that don't support directives either. Additionally this would not work for documentation comments inherited from symbols outside your control, like subclasses of and conformances to symbols defined in 3rd-party libraries.

because SymbolGraphGen emits source location information for doccomments, it would not be necessary to use the @version directive on every doccomment; it could be applied on a file- or even directory-wise basis.

The symbol graph only emits decl-attached doc comments, so we would either need to change that or you would still need to attach the directive to some specific symbol in the file. I'd find it confusing to apply file-wide scope in that case.

I'd suggest that tools that wish to enable a migration path should implement a syntax rewriter that can be run in one pass.

3

no, but if a documentation tool does support multiple dialects (for example, the DocC dialect, and that used by the standard library / SwiftNIO), it would need to know what dialect to parse the doccomment as. to make this concrete, the traditional means of creating asides in Swift is with an UnorderedList, but DocC uses BlockQuotes instead. the situation is even more messy with “Parameters”/“Returns” detection.

because aside and parameter detection generates a lot of false positives, it is not desirable for tooling to accept both forms at the same time; it’s better to be able to specify which syntax the tooling should use.

you would be surprised at the amount of documentation that is already falling through the cracks because of syntax differences like these.

example: system/filedescriptor/duplicate(as:retryoninterrupt:) , the documentation for the target parameter was lost because it was written in backticks.

of course tooling would have to start supporting block directives in order to use @version, there’s no other way to bootstrap this. but compared to the current situation, where there is no tooling directive at all, this would at least be an improvement.

DocC has already introduced a lot of syntax without much consideration for how it fits into or impacts the existing ecosystem, and a lot of this new syntax (like the aside keywords, which seem to have been assigned completely by fiat) isn’t even documented as far as i am aware.

i don’t see how this is relevant. inherited documentation shares the same doccomment as the declaration it was inherited from, so it would use the same syntax as the original doccomment. this is an argument for introducing a version directive like @version, since it may be a different syntax than what the module itself uses.

i don’t think it is reasonable to expect people to employ source formatters to migrate documentation. those of us who work on source tooling tend to be far more trusting of them than the general community, i have found.

4

DocC supports block quote and unordered list asides. Block quote syntax is preferred but not required, and degrades gracefully when rendered by other markdown tools. I'm not familiar with what you're referring to regarding parameter and returns sections. That syntax is unchanged.

Using formatted text in that position was never supported syntax as far as I'm aware. Adding diagnostics to DocC when there's a parameter count/name mismatch or a formatting issue with a list item in a parameters section would be great improvements though.

@version is specifically intended as an interoperability mechanism between documentation tools that cannot support the same syntax, but it only works with the narrow set of tools that can and will support DocC's markdown dialect. And for tools that cannot, this directive may either render oddly or actively break their parsing.

Asides are documented in the Swift DocC documentation, under Add Notes and Other Asides.

I don't agree, but there are other alternatives besides a migrator if you prefer. For example, the tool that one is migrating to could design this syntax themselves in their own native dialect. That would enable the same feature you're proposing, without restricting its use to tools that support directives. For example, a documentation tool based on HTML could use an HTML comment to declare that the rest of the comment uses Jazzy syntax. Long term I think that's the most compelling use case; I don't think a future where there are documentation tools that use slightly different versions of the same syntax is desirable to encourage.

1 Like
5

i think there are a lot of ways you could end up with a parameter name in backticks in that position. the parameter name might be written in backticks in the source declaration itself, and an IDE tool might fill in a blank doccomment by copying it from the source declaration. all parameter names in a project might be intentionally written in backticks in order to provide a better fallback when not rendered in a tool that detects parameters lists.

i agree though, this would be a great feature to have!

there are many more asides in the Aside.Kind enum in swift-markdown than are documented on that page. does DocC only support a subset of them?

i think this is a good idea. thinking about it more, @version would not be as useful as having some way of conditionally including parts of a doccomment into a symbol graph.

however, i don’t think “slightly different” doccomment syntax among swift projects is likely to go away any time soon.

6

Good point, besides the diagnostics it would be a good idea for DocC to just strip all the formatting for parameter names and make a best-effort attempt to understand what you probably meant to do.

1 Like