# What are good ways to structure reoccurring phrases in doc-strings

**URL:** <https://discourse.julialang.org/t/what-are-good-ways-to-structure-reoccurring-phrases-in-doc-strings/118302>\
**Category:** General Usage\
**Created:** [August 17, 2024, 11:12am UTC](https://discourse.julialang.org/t/what-are-good-ways-to-structure-reoccurring-phrases-in-doc-strings/118302 "2024-08-17T11:12:14Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [August 17, 2024, 11:12am UTC](https://discourse.julialang.org/t/what-are-good-ways-to-structure-reoccurring-phrases-in-doc-strings/118302/1 "2024-08-17T11:12:14Z")

</div>

I recently refactored my doc strings after [this discussion](https://discourse.julialang.org/t/best-way-to-document-a-reasonable-amount-of-keywords/112347). In that thread already, @jules wrote, that in Makie they splice a lot of doc strings.

I started doing [something like that](https://github.com/JuliaManifolds/Manopt.jl/blob/kellertuer/rework-high-level-interfaces/src/plans/docstring_snippets.jl) as well collecting phrases I often use, so I can reuse them, have to type them less often (make less typos) and can if necessary change some defaults also in the docs more globally. I also started to unify my LaTeX notation a bit, since I have much more non-raw strings now in order to interpolate.

I do not like my current approach with a loose bunch of Strings. I will change that probably to a dictionary (storing variable names, their defaults, descriptions, etc).

To add an example: A lot of my methods have a parameter `M` the manifold. So, since I also like to add math, a lot of my docs have the line

```julia
* `M`: a Riemannian manifold ``\mathcal M``

```

- sometimes M is even a keyword and has a nice default
- if I write manifold the umptenth time, it comes out as `manifodl`
- Maybe sometime in the future I want to change that (often occuring) snipped for some reason.

so:

Are there other people around doing something like that? Would it maybe be useful coordinating this into something like a `DocumenterGlossary` approach? Would that be useful or a waste of time?

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [August 20, 2024, 3:59pm UTC](https://discourse.julialang.org/t/what-are-good-ways-to-structure-reoccurring-phrases-in-doc-strings/118302/2 "2024-08-20T15:59:22Z")

</div>

Here is a first idea I am currently trying on a PR (cf [Manopt.jl/src/documentation\_glossary.jl at kellertuer/rework-high-level-interfaces · JuliaManifolds/Manopt.jl · GitHub](https://github.com/JuliaManifolds/Manopt.jl/blob/kellertuer/rework-high-level-interfaces/src/documentation_glossary.jl) – please ignore anything below line 213, those are old strings I used before and have not yet replaced)

internally this uses a dictionary of

- Strings – when the snipped is really just a string without any parameters
- Functions – usually with keyword arguments to format a string like `(; M="M") -> "represents the manifold ``$(_tex(:Cal, M))``"`
- further sub dictionaries.

The whole system uses a package local variable `_manopt_glossary` for now, but that is for a single package maybe a reasonable start.  
There is a function `define!` to add entries to the whole glossary, which is meant to be grouped, to for example

```julia
define!(
    :Variable, :p, :description, (; M="M") -> "a point on the manifold ``$(_tex(:Cal, M))``"
)
define!(:Variable, :p, :type, "P")
define!(:Variable, :p, :default, (; M="M") -> _link(:rand; M=M))

```

as well as `_var(args...; kwargs...) = glossary(:Variables, args...; kwargs...)` (similarly `_links` maps to the `:Links` dictionary and `rand` is actually a slightly complicated `@extref` link here).

The same way `glossary(:Variable, :p, :description)` would just print the description, with `glossary(:Variable, :p, :description; M="N")` one can change the calligraphic letter in the string.

And one can of course combine these 3 fields of `p` to a nice group meta entries like

```julia
define!(
    :Variable,
    :Argument,
    (s::Symbol, display="$s"; type=false, kwargs...) ->
        "* `$(display)$(type ? "::$(_var(s, :type))" : "")`: $(_var(s, :description;kwargs...))",
)
define!(
    :Variable,
    :Field,
    (s::Symbol, display="$s"; kwargs...) ->
        "* `$(display)::$(_var(s, :type))`: $(_var(s, :description; kwargs...))",
)

```

one gets an

- argument style display with `_var(:Argument, :p)` as `"* `p`: a point on the manifold ``\\mathcal M``"`
- a field style display with `_var(:Field, :p)` as `"* `p::P`: a point on the manifold ``\\mathcal M``"`

ok for now these only differ in the sense that the field display also shows the type.  
Similarly one can default keyword display that also would show the default defined above.

I would say this is still a bit hacked, but makes it already nice to handle (or group) snippets in a unified way.  
I think I will experiment with this and use it within my package. If someone is interested in a maybe better structure as a standalone package, I would also take that in to account. One could maybe also define that in some YAML or so.