# Coordinating community efforts to enrich function docs

**URL:** <https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338>\
**Category:** General Usage\
**Created:** [May 1, 2022, 5:46pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338 "2022-05-01T17:46:58Z")\
**Posts on this page:** 5\
**Page:** 3

<div class="post-metadata">

**Author:** ![Jordan\_Cluts](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jordan_cluts/32/13753_2.png) [@Jordan\_Cluts](https://discourse.julialang.org/u/Jordan_Cluts)\
**Post date:** [May 2, 2022, 11:55am UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/42 "2022-05-02T11:55:02Z")

</div>

> That said, documentation shouldn’t assume prior experience in other languages

As someone not coming from a C background I had stumbled onto the `@sprintf` documentation but have never used it simply because I have no idea how the formatting works. A link to somewhere explaining or an explanation of what “%0.5f” means (and the other syntax the macro takes) would be helpful here.

---

<div class="post-metadata">

**Author:** ![giordano](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/giordano/32/2166_2.png) [@giordano](https://discourse.julialang.org/u/giordano)\
**Post date:** [May 2, 2022, 12:06pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/43 "2022-05-02T12:06:06Z")

</div>

> [@Jordan\_Cluts](#):
>
> A link to somewhere explaining or an explanation of what “%0.5f” means (and the other syntax the macro takes) would be helpful here.

Quoting from the docstring of [`@printf`](https://docs.julialang.org/en/v1/stdlib/Printf/#Printf.@printf)

> For a systematic specification of the format, see [here](https://www.cplusplus.com/reference/cstdio/printf/).

Although I’d argue we shouldn’t use [here links](https://webaccess.berkeley.edu/ask-pecan/click-here), so that’s another low-hanging fruit to take.

---

<div class="post-metadata">

**Author:** ![Jordan\_Cluts](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jordan_cluts/32/13753_2.png) [@Jordan\_Cluts](https://discourse.julialang.org/u/Jordan_Cluts)\
**Post date:** [May 2, 2022, 12:19pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/44 "2022-05-02T12:19:24Z")

</div>

Ah excellent! I never saw that link under the `@printf` docs instead of the `@sprintf` ones. Thank you!

---

<div class="post-metadata">

**Author:** ![IlianPihlajamaa](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ilianpihlajamaa/32/28766_2.png) [@IlianPihlajamaa](https://discourse.julialang.org/u/IlianPihlajamaa)\
**Post date:** [May 2, 2022, 1:50pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/45 "2022-05-02T13:50:15Z")

</div>

While I wholeheartedly support and intend to contribute to this initiative to improve the reference documentation, I think that we first need to discuss what good reference documentation of a function should include, because I believe that consistency is very important there. Specifically, in your [repo](https://github.com/johnmyleswhite/julia-function-docs), you write:

> # What Does Good Documentation Look?
> 
> Non-exhaustively, it’s useful for a function to contain:
> 
> 1. Description: A 1-3 sentence summary of what the function/method does.
> 2. Usage: A theoretical call to the function/method with all arguments.
> 3. Arguments: A list of all arguments, their types and their meaning.
> 4. Returned Values: A list of all returned values, their types and their meaning.
> 5. Details: More details about how the function/method works, how it should be called, how it is implemented, how its returned values are meant to be used, etc.
> 6. References: Bibliographic information
> 7. See Also: Other documentation sections that are relevant and text explaining their relationship to the current function/method.
> 8. Examples: Specific examples that show what using the function/method in practice would look like.

As far as I can tell (almost) no function in the documentation right now satistfies these eight points. For example, let’s look at [the reference](https://docs.julialang.org/en/v1/base/math/) for arguably the most used function: `Base.:+`.

Right now, it includes only the methods for `dt::Date + t::Time -> DateTime` and `+(x, y...)`. It says nothing about `+(x::T, y::T) where T<:Union{Int128, Int16, Int32, Int64, Int8, UInt128, UInt16, UInt32, UInt64, UInt8}` which is probably the most used. More generally, very rarely the function documentation explicitly specifies the return type of the function or its meaning. And for a reason, since that would e.g. entail that all 100+ methods of `+` have to be mentioned.

What I want to say is this: let’s first discuss what a good reference would look like, with simple multimethod functions like `+` in mind. Then, a list of functions can be made whose docs are not up that standard. If you all agree with this, I would like to contribute to creating that list and writing the references (although my git skills are not so good).

---

<div class="post-metadata">

**Author:** ![IlianPihlajamaa](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ilianpihlajamaa/32/28766_2.png) [@IlianPihlajamaa](https://discourse.julialang.org/u/IlianPihlajamaa)\
**Post date:** [May 2, 2022, 1:57pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/46 "2022-05-02T13:57:33Z")

</div>

(On the short term, we should probably not put the `dt::Date + t::Time -> DateTime` method of `+` as the first entry in the documentation of the maths section)

[Previous page](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338.md?page=2)