JuliaDocs / JuliaDocs/DocStringExtensions.jl
Would it be possible to add a TYPEDMETHODLIST abbreviation
Nobody has claimed this yet.
- Dominant language
- Julia
- Stars
- 126
- Forks
- 35
- PR merge metrics
- No merged PRs in 30d
Description
Currently I have a module set up like this
module abcFunctionsModule
using DocStringExtensions
DocStringExtensions.@template TYPES =
"""
$(TYPEDEF)
# Descriptions
$(DOCSTRING)
"""
DocStringExtensions.@template (FUNCTIONS) =
"""
$(METHODLIST)
# Description
$(DOCSTRING)
# Examples
"""
DocStringExtensions.@template (METHODS, MACROS) =
"""
$(DOCSTRING)
"""
include("myFunc1.jl")
include("myFunc2.jl")
end
myFunc1.jl file looks like this
"""
An example function which will later be placed in a module to be imported/used elsewhere.
"""
function myFunc1 end
#this is the empty function definition (i.e it declares a function with 0 methods) and is where we document the `description of the function.
"""
## Example with no arguments
myFunc1() ----> $(myFunc1())
"""
function myFunc1()
return "MyFunc1"
end
"""
## Example with int
myFunc1(5) ----> $(myFunc1(5))
"""
function myFunc1(x::Int64)
return "MyFunc1 with an int $x"
end
"""
## Example with string
myFunc1("me") ----> $(myFunc1("me"))
"""
function myFunc1(x::String)
return "MyFunc1 with a string that says $x"
end
This does 99% of what I want it to. i.e. DocStringExtensions correctly adds the #Decription and #Examples heading and then adds each example as per the documentation above each method.
However $METHODLIST outputs this
so for the last two methods of myFunc1 ( one that takes in a string and the other that takes in a int) you can't see immediately what the input is because they both show up as
myFunc(x)
Note I cannot do this with TYPEDSIGNATURES in each individual method docString as i specifically want a doc sting like this
"""
# the methods/signatures
# then description
# then examples
# with each example being found in the method DocString to limit duplication/ adhere to single source of truth
"""
function xyz end ....etc
Would it be possible to add the typed signatures/ typed method list by creating a new $TYPEDMETHODLIST abbreviation similar to how it is done for $TYPEDSIGNATURES
I could then create the module as described above and everything would show up nicely/just work. And I would be able to distinguish between which method is which
I would be happy to contribute to a PR. I am a novice when it comes to meta-programming so guidance on what to do/where to look would be appreciated
Many thanks in advance
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing how the TYPEDSIGNATURES abbreviation is implemented with the existing METHODLIST template behavior in DocStringExtensions. Define the expected TYPEDMETHODLIST output from the myFunc1 example, including each method's argument types, and verify that the module template renders distinct signatures.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- julia
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100