DocString templates

[sivark]

It would be very convenient to have a docstring "template" which can be made to apply to all functions in a module. Eg: one could define at the start of a module that each docstring will present function names with type signatures, default argument values and a url to the function definition.

Also part of the template could be a slot (abbreviation?) where locally defined docstrings would be filled in. Eg: When one describes some detail specific to a function, that description could get filled in between the type signature and the url, if the programmer so chooses.

[MichaelHatherly]

Any idea how you'd like these templates to look? How would they be applied to individual "untemplated" docstrings, i.e. how would you mark which part of each docstring gets inserted into each template "slot"?

[sivark]

Right now, one gets to specify a template for the docstring of each function (and some details get filled into the template). I was instead thinking of a global template that would apply to all functions in a module, so that

1. The same template need not be repeated for each function, making it more convenient for the programmer.
2. It could automatically introduce some uniformity in documentation.

This is a rough sketch of the structure I had in mind:

@GlobalTemplate FunctionDocstring
"""
$(SIGNATURES(:with_types))

$(DESCRIPTION)

$(URL)
"""

where $(DESCRIPTION) is any content that is located where the docstring for a function is conventionally located.

I hadn't imagined the possibility of some functions/docstrings overriding this template. Maybe one can arrange for that with a suitable flag.

[MichaelHatherly]

Thanks for clarifying that, DESCRIPTION was the part I was looking for I think. So all the content from each docstring would just be spliced into it's place, which sounds reasonable to me, would there be cases where one would want to intersperse parts of the description with the different abbreviations perhaps?

URL is probably not something that should really be included since it's already output by Documenter.jl itself. We could possibly just filter out potentially duplicate info during doc rendering though.

Would you want to be able to define different templates for different categories such as method, type, macro, const, etc? I'd imagine that would probably be useful.

[sivark]

would there be cases where one would want to intersperse parts of the description with the different abbreviations perhaps?

I'm not able to think of a compelling need right now; might just be a lack
of imagination.

URL is probably not something that should really be included since it's already output by Documenter.jl itself. We could possibly just filter out potentially duplicate info during doc rendering though.

Fair enough. That was only an illustration; the user could remix whatever
abbreviations the library exports, into the global template.

Would you want to be able to define different templates for different categories such as method, type, macro, const, etc? I'd imagine that would probably be useful.

Yes, that's what I had in mind. Maybe all those templates could be
collected in a separate file as convenient.

[MichaelHatherly]

We could also probably provide a couple of default templates that package authors can just use out-of-the-box.