Examples of how to use all of the functionality

[andyDoucette]

This seems like a great package! One thing that's really missing is an example of how to use each and every functionality. Ideally, this would be a single page with two columns. The left would be the function definitions and the right would be the rendered help text.

More specifically, I'm currently struggling to find out how to use the FIELDS variable effectively to document the arguments to a functoin without me having to duplicate the names of all of the variables (single source of truth!!!). Let's say I have this function:

function calculate_retirement_monthly_savings(startingAmount::Number, # How much money you have now,
                                              yearsTillDie::Number, #How many years you have to live
                                              currentYearlyExpenses, #What you spend now (assuming you want the same quality of life when you retire
                                              yearlyInflation::AbstractFloat, #A number slightly greater than 1 specifying buyingPowerAYearAgo/buyingPowerNow for a given amount of money.)

It would be great if those comments could make it to an argument list, with the types, but without having to duplicate (and possibly cause inconsistencies) the variable names. Is that possible with the existing pacakge? I don't currently know because I can't find examples of how to use the FIELDS variable effectively

[tpapp]

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.

[MichaelHatherly]

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.

[andyDoucette]

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. 🙏

[prakaa]

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

[johannesnauta]

I know I am late, but the above use of the @templates macro does not appear to work for me. If I set, for example

@template DEFAULT =
    """
    $(TYPEDSIGNATURES)
    $(DOCSTRING)
    """

and have some function in an included module

"""
Some docstring
"""
function some_func(x::Float64, y)
   return nothing  
end

The function does not show typed signatures as suggested by setting the DEFAULT template. Am I missing something?