Linker option for stringify
tmcw opened this issue · 6 comments
I'd love to switch documentation.js's type formatting to doctrine's own, so that it can support the full range of output. Right now, though, there's a strong emphasis on type interlinking in documentation.js - everything from user types to JS primitives either interlink or link to MDN. I'd like to keep this in the switch.
One way to implement this would be to supply a 'linker' option to the stringify method. Would you be open to this sort of PR?
I'm not familiar with documentation.js, can you explain what type interlinking is? And can you explain what a linker option would do and how it would be used?
Sure: so in generated HTML documentation, type annotations like Array<string> are linked: the word "Array" links to the MDN article about the Array object, same with string. If you have a type like Array<Comment>, where Comment is an available namepath, it'll link that to the section of documentation talking about that namepath.
A linker option would allow the stringify method to look at a given namepath and optionally return an HTML or markdown link instead of the literal string.
I'm pretty unfamiliar with stringify(), but I'm trying to understand. It looks like, given a type AST, it will create the text representation of it. It seems like a linker, as you describe, would be a super specific use case that I'm not sure makes sense as part of that function.
Can you explain some more about how you'd envision this working and what the output would be? Also, why, could you write a custom serializer that did this for you?
Also, why, could you write a custom serializer that did this for you?
That's what documentation.js does currently: it serializes doctrine's output into HTML & Markdown structures. It took me a while to realize that doctrine itself had a utility for doing this, and thus maybe it would be better to use the existing upstream code rather than implement it ourselves - but if a linker seems out of scope for doctrine we can stick with a homegrown implementation.
I think a linker is too specific for doctrine. I'm just curious if there's a more generic solution that could be used for your use case as well as others. Like maybe a replacer function similar to the second argument of JSON.stringify (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter)
Okay, agreed - we'll stick to writing a formatter in documentation.js itself.