JuliaDocs / JuliaDocs/DocStringExtensions.jl

Would it be possible to add a TYPEDMETHODLIST abbreviation

Open
#150 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Feature up for grabs
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.
image

However $METHODLIST outputs this
image
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.