Examples of how to use all of the functionality about docstringextensions.jl HOT 5 OPEN

Thanks for the clarification on FIELDS! I'll have to read the section on julia macros to understand your suggestion. Just so this doesn't get closed prematurely, the most important part of this issue is to get a page of examples if at all possible. 🙏

from docstringextensions.jl.

AFAIK FIELDS is for documenting fields of a composite type (struct, mutable struct), not function arguments.

Typically one does something like

"""
$(SIGNATURES)

# Arguments

- `startingAmount`: how much money you have now
- ...
"""
function calculate_retirement_monthly_savings(startingAmount::Number, ...

which indeed duplicates argument names.

from docstringextensions.jl.

Yes, FIELDS is for structs. You could write a macro that wraps a function definition and it's docstring that allows you to avoid extra typing and works something like

@document_arguments begin
    """
    $(ARGUMENTS)
    """
    function func(
        "docs for `arg`" ->
        arg,
    )
        # ...
    end
end

which would pull out the "..." -> expressions and place them in a formatted list in place of ARGUMENTS.

from docstringextensions.jl.

On this, I think it could be helpful to document/include an example on how to use @template, e.g.:

Define your templates in your PackageName.jl. This must be done before including files:

...
#DocStringExtensions Templates
using DocStringExtensions
@template (FUNCTIONS, METHODS) = """
                                 $(TYPEDSIGNATURES)
                                 $(DOCSTRING)
                                 $(METHODLIST)
                                 """
@template TYPES = """
                  $(TYPEDEF)
                  $(TYPEDFIELDS)
                  $(DOCSTRING)
                  """
# file includes
include("somefile1.jl")
include("somefile2.jl")
...

This could also address #117

from docstringextensions.jl.