I’m imagining writing something like
@doc_with_sig """
Return a car with the given list of wheels and the given engine.
Throws an error if `engine` doesn't have enough horsepower.
""" function make_car(wheels::Vector{Wheel}, engine::Engine)
such that make_car gets the docstring
make_car(wheels::Vector{Wheel}, engine::Engine)Return a car with the given list of wheels and the given engine.
Throws an error if
enginedoesn’t have enough horsepower.
I realize it would not be desirable to use this macro all the time, including for functions that have many methods that conceptually all do the same thing. But in many of my use cases, having such a macro would be useful and result in code and docs being more readable and/or more maintainable than the two alternatives:
-
“Write the function signature manually.” This can end up being a large violation of Don’t Repeat Yourself, especially in cases where the documentation is simply the function signature followed by one short sentence. And I usually try to write code where that is the norm, i.e. code that strives to be digestible and self-documenting where possible.
-
“Don’t include the function signature.” As shown in the example above, including the function signature helps clarify the argument order, and also allows me to refer to the function arguments by name in the prose description of what the function does.
Before I try to learn enough of the reflection API to implement this macro, wondering if others have comments or improvements to this idea?
