# What is the standard documentation format when writting docstrings of parametric-type

**URL:** <https://discourse.julialang.org/t/what-is-the-standard-documentation-format-when-writting-docstrings-of-parametric-type/1293>\
**Category:** Internals & Design\
**Tags:** package, documentation\
**Created:** [January 5, 2017, 3:22am UTC](https://discourse.julialang.org/t/what-is-the-standard-documentation-format-when-writting-docstrings-of-parametric-type/1293 "2017-01-05T03:22:32Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [January 5, 2017, 3:22am UTC](https://discourse.julialang.org/t/what-is-the-standard-documentation-format-when-writting-docstrings-of-parametric-type/1293/1 "2017-01-05T03:22:32Z")

</div>

Hello I am writing a small little package and now I am editing the documentation strings. My question is the following:  
Which of the following two is the preferred/most idiomatic in Julia?  
First:

```julia
"""
`cyclotron{T<:AbstractFloat}(p::AbstractParticle{T}, ω::T)`
Return center and radius of circular motion performed by the particle based on
p.pos and p.vel.
"""

```

or second:

```julia
"""
`cyclotron(p::AbstractParticle, ω)`
Return center and radius of circular motion performed by the particle based on
p.pos and p.vel.
"""

```

In the second example I am removing the parametric type information.

---

<div class="post-metadata">

**Author:** ![mike](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mike/32/39_2.png) [@mike](https://discourse.julialang.org/u/mike)\
**Post date:** [January 5, 2017, 5:55am UTC](https://discourse.julialang.org/t/what-is-the-standard-documentation-format-when-writting-docstrings-of-parametric-type/1293/2 "2017-01-05T05:55:50Z")

</div>

> [@George\_Datseris](#):
>
> Which of the following two is the preferred/most idiomatic in Julia?

Depends on what your users need to know about when reading your docs. If `T` is an important parameter that the user has to be aware of when calling `cyclotron` then probably best to include it and also mention it within the body of the docstring. If it’s not useful for the user to know about it then I’d say just leave it out to make the signature simpler to read.

Do note that the signatures that appear at the top of docstrings don’t need to be _exact_ copies of the actual method signatures at all. They are just there to tell the user enough to be able to call the method successfully. Also, if you’d like to have Julia write the signatures for you itself then the following package might be of some use

> **[GitHub - JuliaDocs/DocStringExtensions.jl: Extensions for Julia's docsystem.](https://github.com/JuliaDocs/DocStringExtensions.jl)**
>
> Extensions for Julia's docsystem. Contribute to JuliaDocs/DocStringExtensions.jl development by creating an account on GitHub.