Enablement of DocC Extension Support as an Opt-In Feature

Development Swift-DocC
21

Completely separate; I'm curious if you have any ideas for how you would prefer to phrase that warning (when DocC can't find a given page either in the sub hierarchy from the source page (the documentation comment where the link is) or in or the sub hierarchies of any of its containers (the class/struct/enum that contains the source page, etc.)).

I've been thinking about this phrasing some but haven't really found any alternative that I really like. One alternative that I've considered is 'String' isn't a member of '/meals/Vapor/Validator/phone' but that structurally the same and only a slight improvement when there's a near-miss suggestion of a similarly spelled name that would resolve.

One thing that I dislike about both those phrasings is that they're implying that DocC only searches for the page in the sub hierarchy of the source page (and not its containers). I've been thinking about if it would help to look up the kind of each container page and list them out, in either ascending or descending order), something like:
'String' isn't a member of either instance property 'phone', structure 'Validator', or module 'Vapor'.

1 Like
22

Well, my concern is a little wider than just this issue. I've noticed that the rendered documentation absolutely buries my extensions. In a Vapor app, it's very common to add functionality to Request or Application, and those are first-class citizens in my app, but they're several levels deep in the ToC in the rendered docs.

The same thinking seems to be surfacing here, that my extension is not a first-class citizen of my app, and so I have to reference it as part of Swift.

So, sure, a message telling me to add Swift/ can help me get my docs rendered, but it’s not ideal.