# Seems useful to write a macro that prepends the method signature to the docstring?

**URL:** <https://discourse.julialang.org/t/seems-useful-to-write-a-macro-that-prepends-the-method-signature-to-the-docstring/44598>\
**Category:** Internals & Design\
**Created:** [August 9, 2020, 3:37am UTC](https://discourse.julialang.org/t/seems-useful-to-write-a-macro-that-prepends-the-method-signature-to-the-docstring/44598 "2020-08-09T03:37:41Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![bzinberg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bzinberg/32/30798_2.png) [@bzinberg](https://discourse.julialang.org/u/bzinberg)\
**Post date:** [August 9, 2020, 3:37am UTC](https://discourse.julialang.org/t/seems-useful-to-write-a-macro-that-prepends-the-method-signature-to-the-docstring/44598/1 "2020-08-09T03:37:41Z")

</div>

I’m imagining writing something like

```julia
@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

> ```julia
> make_car(wheels::Vector{Wheel}, engine::Engine)
> 
> ```
> 
> Return a car with the given list of wheels and the given engine.
> 
> Throws an error if `engine` doesn’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:

1. “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.

2. “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?

---

<div class="post-metadata">

**Author:** ![rdeits](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rdeits/32/286_2.png) [@rdeits](https://discourse.julialang.org/u/rdeits)\
**Post date:** [August 9, 2020, 3:57am UTC](https://discourse.julialang.org/t/seems-useful-to-write-a-macro-that-prepends-the-method-signature-to-the-docstring/44598/2 "2020-08-09T03:57:51Z")

</div>

Check out `SIGNATURES` from [DocStringExtensions](https://juliadocs.github.io/DocStringExtensions.jl/stable/), which pretty much does what you’re asking for here 🙂

---

<div class="post-metadata">

**Author:** ![baggepinnen](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/baggepinnen/32/693_2.png) [@baggepinnen](https://discourse.julialang.org/u/baggepinnen)\
**Post date:** [August 9, 2020, 7:05am UTC](https://discourse.julialang.org/t/seems-useful-to-write-a-macro-that-prepends-the-method-signature-to-the-docstring/44598/3 "2020-08-09T07:05:06Z")

</div>

See also [https://github.com/baggepinnen/AutomaticDocstrings.jl](https://github.com/baggepinnen/AutomaticDocstrings.jl) if you want to semi automate the creation of the docstring.

---

<div class="post-metadata">

**Author:** ![bzinberg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bzinberg/32/30798_2.png) [@bzinberg](https://discourse.julialang.org/u/bzinberg)\
**Post date:** [August 9, 2020, 5:58pm UTC](https://discourse.julialang.org/t/seems-useful-to-write-a-macro-that-prepends-the-method-signature-to-the-docstring/44598/4 "2020-08-09T17:58:20Z")

</div>

Wonderful, thank you!