# 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:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 5:46pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/1 "2022-05-01T17:46:58Z")

</div>

Following up on some of the positive suggestions in [a recent thread](https://discourse.julialang.org/t/blog-post-about-my-experiences-with-julia/79976), I’d like to use this thread to coordinate efforts with anyone who feels Julia’s function-level documentation can be better. Discourse lacks the ability to create a user-extensible poll, so please:

1. Suggest functions whose documentation can be improved.
2. Volunteer here to take on efforts.

I’m happy to help efforts to lead folks to make progress, but would like to see some contributions from those asking for improvements since they are presumed to represent those not being well-served by the current documentation.

---

<div class="post-metadata">

**Author:** ![ufechner7](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ufechner7/32/51363_2.png) [@ufechner7](https://discourse.julialang.org/u/ufechner7)\
**Post date:** [May 1, 2022, 6:42pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/2 "2022-05-01T18:42:12Z")

</div>

Base.sleep

needs an explanation how to sleep for less than 1ms or with a resolution better than 1ms, e.g. a link to Base.Libc.systemsleep

---

<div class="post-metadata">

**Author:** ![ufechner7](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ufechner7/32/51363_2.png) [@ufechner7](https://discourse.julialang.org/u/ufechner7)\
**Post date:** [May 1, 2022, 6:56pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/3 "2022-05-01T18:56:52Z")

</div>

sin and cos

Both functions have dead links to sind and friends

---

<div class="post-metadata">

**Author:** ![DNF](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dnf/32/10191_2.png) [@DNF](https://discourse.julialang.org/u/DNF)\
**Post date:** [May 1, 2022, 7:17pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/4 "2022-05-01T19:17:22Z")

</div>

I started looking at the letter ‘a’.

`abs` is fine, and includes an explanation of overflow for large negative numbers.

`abs2`, on the other hand, has the same issue, but does not include the explanation about overflow, and is generally much more sparse. It should probably also include a brief mention of why it exists, i.e. for performance reasons. If the performance aspect is left out, the function seems quite pointless. It also lacks a “see also” section.

This is as far as I got at the moment 😆

---

<div class="post-metadata">

**Author:** ![rafael.guerra](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rafael.guerra/32/216610_2.png) [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)\
**Post date:** [May 1, 2022, 7:25pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/5 "2022-05-01T19:25:57Z")

</div>

The `copy()` function is described as a “shallow copy” in the REPL documentation. To a non-programmer like me, it seems shocking that a function with such a name could ever fail to copy a Julia object. The doc should explain that it fails if the objects contain immutable elements, or whatever is the right explanation.

An example of what I’m talking about:

```julia
ntup = (v = [0, 1], s = 2)
copy(ntup)
ERROR: MethodError: no method matching copy

```

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 7:29pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/6 "2022-05-01T19:29:50Z")

</div>

This is a good one, but I think you’re confusing how copy should work on immutable typed values from the distinction between shallow and deep copies. `copy(1)`, for example, does work. I would interpret this as method gap – perhaps intentional, but definitely distinct from the shallow/deep distinction.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 7:44pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/8 "2022-05-01T19:44:11Z")

</div>

If I create a new function `f(x::Float64)` and you call it like `f(1)`, it will fail with a MethodError:

```julia
julia> f(x::Float64) = x + 1.0
f (generic function with 1 method)

julia> f(1)
ERROR: MethodError: no method matching f(::Int64)

```

This is exactly what’s happening in your example: there’s no method for `copy` that applies in your example. You might argue that (a) Julia should have a definition for all possible types or that (b) Julia should at least have definitions for “core” types like `Tuple`. I’m sympathetic to (a), but the general feeling is that Julia don’t do this. I fully agree with (b) and think submitting a PR that adds `copy` for `Tuple` is useful. You might find the current committers disagree, but that presumably depends on them disagreeing with (b).

---

<div class="post-metadata">

**Author:** ![rafael.guerra](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rafael.guerra/32/216610_2.png) [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)\
**Post date:** [May 1, 2022, 7:51pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/9 "2022-05-01T19:51:44Z")

</div>

> [@johnmyleswhite](#):
>
> You might argue

No, I do not have the necessary knowledge and I have full confidence in the skill of Julia’s developers. This request is simply about the docstring to explain to the users when the `copy()` function is supposed to fail.

---

<div class="post-metadata">

**Author:** ![ImreSamu](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/imresamu/32/20677_2.png) [@ImreSamu](https://discourse.julialang.org/u/ImreSamu)\
**Post date:** [May 1, 2022, 7:59pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/10 "2022-05-01T19:59:28Z")

</div>

> [@DNF](#):
>
> `abs` is fine, and includes an explanation of overflow for large negative numbers.

[https://docs.julialang.org/en/v1.9-dev/base/math/#Base.abs](https://docs.julialang.org/en/v1.9-dev/base/math/#Base.abs)

but we can improve

1.) by adding links ( with external info / images )

- [Absolute value - Wikipedia](https://en.wikipedia.org/wiki/Absolute_value)
- [Absolute value - Encyclopedia of Mathematics](https://encyclopediaofmath.org/index.php?title=Absolute_value)

2.) by adding images: from the ( Wikimedia servers )  
( [Absolute\_value.svg](https://en.wikipedia.org/wiki/File:Absolute_value.svg) )  
 ![](https://global.discourse-cdn.com/julialang/original/3X/b/d/bd8a33bcd19e9610bc606836ca09410b1336cca6.png)

3.) using **wikidataId**  
for fetching labels / Descriptions / images in different languages.  
( and helping [Julia Diversity statement](https://julialang.org/diversity/) )

check [absolute value : Q120812 Wikidata](https://www.wikidata.org/wiki/Q120812) / ( [json](https://www.wikidata.org/wiki/Special:EntityData/Q120812.json) )

it is a “public domain” information!

we can use the “Labels”:

```json
"labels": {
"en": {
"language": "en",
"value": "absolute value"
},
"zh-hans": {
"language": "zh-hans",
"value": "绝对值"
},
"zh-hant": {
"language": "zh-hant",
"value": "絕對值"
},
"es": {
"language": "es",
"value": "valor absoluto"
},
"fr": {
"language": "fr",
"value": "valeur absolue"
},
"hu": {
"language": "hu",
"value": "abszolútérték-függvény"
},
....

```

Descriptions:

```json
"descriptions": {
"en": {
"language": "en",
"value": "nonnegative number with the same magnitude as a given real number"
},
"fr": {
"language": "fr",
"value": "distance à 0, valeur numérique d'un nombre réel sans tenir compte de son signe"
},
"pl": {
"language": "pl",
"value": "funkcja matematyczna, wartość liczbowa nieuwzględniająca znaku danej liczby"
},

```

Alias:

```json
"en": [
{
"language": "en",
"value": "|x|"
},
{
"language": "en",
"value": "absolute value function"
},
{
"language": "en",
"value": "absolute value of real number"
},
{
"language": "en",
"value": "modulus"
},
{
"language": "en",
"value": "magnitude"
},
{
"language": "en",
"value": "absolute value of a real number"
}
],
"hu": [
{
"language": "hu",
"value": "abszolút érték"
}
],

```

the image

```json
"P18": [
{
"mainsnak": {
"snaktype": "value",
"property": "P18",
"hash": "6ba52a602ff5eb8b9d907a4620629ac8ff5eb13a",
"datavalue": {
"value": "AbsoluteValueDiagram.svg",
"type": "string"
},
"datatype": "commonsMedia"
},
"type": "statement",
"id": "Q120812$6ce5c855-4f53-e845-8360-895a08fc4c9d",
"rank": "normal"
}
],

```

the “defining formula” ; etc …

AND via [wikidata:Q120812](https://www.wikidata.org/wiki/Q120812) ` we can add more links …

- Encyclopædia Britannica Online ID → [Absolute value | Definition, Symbol, & Facts | Britannica](https://www.britannica.com/science/absolute-value)
- MathWorld identifier → [Absolute Value -- from Wolfram MathWorld](https://mathworld.wolfram.com/AbsoluteValue.html)
- Online PWN Encyclopedia (PL) → [wartość bezwzględna, Encyklopedia PWN: źródło wiarygodnej i rzetelnej wiedzy](https://encyklopedia.pwn.pl/haslo/;3876849.html)

4.) If we create a permanent\_JuliaID - We can also add this link to Wikidata! ( cross-link )

---

<div class="post-metadata">

**Author:** ![tomerarnon](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tomerarnon/32/3170_2.png) [@tomerarnon](https://discourse.julialang.org/u/tomerarnon)\
**Post date:** [May 1, 2022, 8:01pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/11 "2022-05-01T20:01:35Z")

</div>

I don’t think it’s “supposed” to fail. `copy` has 15 methods defined in Base. By contrast `deepcopy` has only 1 that applies generically to all objects. `copy` is mostly intended for shallow-copying containers (although there are exceptions). Methods for `Tuple` and `NamedTuple` are not defined, but I doubt there is good reason for this, since methods for e.g. `Number`/ `AbstractRange` are; if you made a PR it would probably be accepted.

I think the docs for `copy` should definitely mention `deepcopy`.

---

<div class="post-metadata">

**Author:** ![Volker\_Weissmann](https://avatars.discourse-cdn.com/v4/letter/v/c2a13f/32.png) [@Volker\_Weissmann](https://discourse.julialang.org/u/Volker_Weissmann)\
**Post date:** [May 1, 2022, 8:21pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/12 "2022-05-01T20:21:06Z")

</div>

I added some missing links:

[https://github.com/JuliaLang/julia/pull/45139/files](https://github.com/JuliaLang/julia/pull/45139/files)

---

<div class="post-metadata">

**Author:** ![DNF](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dnf/32/10191_2.png) [@DNF](https://discourse.julialang.org/u/DNF)\
**Post date:** [May 1, 2022, 8:21pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/13 "2022-05-01T20:21:39Z")

</div>

- `abspath` lacks examples, and should point to `joinpath` and other related functions.

> [@ImreSamu](#):
>
> but we can improve

Holy moly! I was going to volunteer to improve some docstrings, but now I think I would be in over my head. Can you explain what some of that stuff is? Wikidataid? Labels? ehm. etc?

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 8:32pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/14 "2022-05-01T20:32:09Z")

</div>

I would skip some of the suggested Wikipedia links for now. I think it’s setting the bar too high in a way that will stifle community work. To make progress on stuff like this, you really need to build momentum first with a relatively low bar for participation.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 8:38pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/15 "2022-05-01T20:38:42Z")

</div>

I’ve created a [GitHub repo](https://github.com/johnmyleswhite/julia-function-docs) to try to help to coordinate work here. I’ve compiled the functions listed so far, proposed improvements and left blanks for the people who will take responsibility for writing and reading/reviewing proposed edits.

If you’d like to be writer/reader, please open an issue and suggest yourself. Even better is to make a PR that changes the tracking CSV file so we have a record of your request.

I volunteer to help write edits for `Base.sleep` to get us started.

---

<div class="post-metadata">

**Author:** ![mcabbott](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mcabbott/32/6603_2.png) [@mcabbott](https://discourse.julialang.org/u/mcabbott)\
**Post date:** [May 1, 2022, 8:51pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/16 "2022-05-01T20:51:26Z")

</div>

[This PR](https://github.com/JuliaLang/julia/pull/45141) should expand `abs2` a bit.

I wonder if making this [CSV file](https://github.com/johnmyleswhite/julia-function-docs/blob/main/functions.csv) something like a github discussion page might make it easier to use, link to PRs, etc.

---

<div class="post-metadata">

**Author:** ![ericphanson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ericphanson/32/215186_2.png) [@ericphanson](https://discourse.julialang.org/u/ericphanson)\
**Post date:** [May 1, 2022, 8:57pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/17 "2022-05-01T20:57:02Z")

</div>

Another option is to make an issue template and then ask folks to file them as issues. Can be pretty easy.

---

<div class="post-metadata">

**Author:** ![bkamins](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bkamins/32/208538_2.png) [@bkamins](https://discourse.julialang.org/u/bkamins)\
**Post date:** [May 1, 2022, 8:57pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/18 "2022-05-01T20:57:23Z")

</div>

I have opened [Define copy for immutable values · Issue #45143 · JuliaLang/julia · GitHub](https://github.com/JuliaLang/julia/issues/45143) to discuss this issue. I think it is safe to define `copy` for immutable values as identity.

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 8:59pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/19 "2022-05-01T20:59:58Z")

</div>

I’m open to that, but assuming people keep participating, I think there’s some value in continuing to use an enforced schema that all suggestions are measured against to be able to do retrospective analysis, etc.

I guess my question before I turn on discussions – what’s the benefit versus a discussion on Discourse?

---

<div class="post-metadata">

**Author:** ![ImreSamu](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/imresamu/32/20677_2.png) [@ImreSamu](https://discourse.julialang.org/u/ImreSamu)\
**Post date:** [May 1, 2022, 9:01pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/20 "2022-05-01T21:01:41Z")

</div>

> [@DNF](#):
>
> Holy moly! I was going to volunteer to improve some docstrings, but now I think I would be in over my head. Can you explain what some of that stuff is? Wikidataid? Labels? ehm. etc?

sorry; just skip the second part of the info

Probably you can use the relevant Wikipedia page

- wikimedia images:  
`![alternative text](link/to/image.png)`  
( I can’ see examples in the current doc … it is valid ? )
- adding wikipedia links:  
`[three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic)` ([bool.jl doc](https://github.com/JuliaLang/julia/blob/afdd6bd2795ade4713259c1e4a651d8420ecfe83/base/bool.jl#L46=) )

You can find more examples in the current code:

- [https://github.com/JuliaLang/julia/search?l=Julia&q=wikipedia&type=code](https://github.com/JuliaLang/julia/search?l=Julia&q=wikipedia&type=code)

---

<div class="post-metadata">

**Author:** ![johnmyleswhite](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/johnmyleswhite/32/31_2.png) [@johnmyleswhite](https://discourse.julialang.org/u/johnmyleswhite)\
**Post date:** [May 1, 2022, 9:02pm UTC](https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/21 "2022-05-01T21:02:42Z")

</div>

I like this, but worry that it aggregates some things that may slow people down while disaggregating some other things:

1. It makes it easy to propose changes to the text without modifying the code itself, so it splits those two apart.
2. It requires making any progress to go through the full Julia PR process, rather than some more white glove with an assigned writer/reader pairing.

If this stalls out in 1-2 weeks, let’s revisit and consider trying your style instead.

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