Comments (5)
We could also probably provide a couple of default templates that package authors can just use out-of-the-box.
from docstringextensions.jl.
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"?
from docstringextensions.jl.
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
- The same template need not be repeated for each function, making it more convenient for the programmer.
- 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.
from docstringextensions.jl.
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.
from docstringextensions.jl.
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.
from docstringextensions.jl.
Related Issues (20)
- How to use alias of AbstractArray instead of the full name? (Feature request) HOT 2
- Display parametric types in a better way? HOT 2
- Remove documentation page for v0.1
- Update CI badges in the README HOT 2
- TagBot trigger issue HOT 7
- The `TYPES` template does not apply to parametric types
- MODULES key not found for `@template` HOT 1
- Doctest failures
- Format docstrings HOT 4
- Considering writing a script to add function signatures to a code base. HOT 5
- Examples of how to use all of the functionality HOT 5
- expected test failure from the incoming `Core.Compiler` changes HOT 3
- Cannot get source for generated functions
- feature request: non-api doc marker HOT 3
- How to show default values and types of keyword arguments? HOT 1
- Update docs to latest version of Documenter HOT 5
- different abbreviations for concrete and abstract types HOT 1
- FUNCTIONNAME inside a function that generates the docstring HOT 7
- Would it be possible to add a TYPEDMETHODLIST abbreviation HOT 2
- Internal errors when (ab)using `@template` HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docstringextensions.jl.