Coordinating community efforts to enrich function docs

General Usage
1

Following up on some of the positive suggestions in a recent thread, 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.

23 Likes
2

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

4 Likes
3

sin and cos

Both functions have dead links to sind and friends

3 Likes
4

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 :laughing:

7 Likes
5

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:

ntup = (v = [0, 1], s = 2)
copy(ntup)
ERROR: MethodError: no method matching copy
5 Likes
6

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.

1 Like
8

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

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).

1 Like
9

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.

1 Like
10

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

but we can improve

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

2.) by adding images: from the ( Wikimedia servers )
( Absolute_value.svg )

3.) using wikidataId
for fetching labels / Descriptions / images in different languages.
( and helping Julia Diversity statement )

check absolute value : Q120812 Wikidata / ( json )

it is a “public domain” information!

we can use the “Labels”:

"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:

"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:

"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

"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 ` we can add more links …

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

2 Likes
11

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.

3 Likes
12

I added some missing links:

https://github.com/JuliaLang/julia/pull/45139/files

5 Likes
13
  • abspath lacks examples, and should point to joinpath and other related functions.

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?

1 Like
14

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.

11 Likes
15

I’ve created a GitHub repo 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.

5 Likes
16

This PR should expand abs2 a bit.

I wonder if making this CSV file something like a github discussion page might make it easier to use, link to PRs, etc.

3 Likes
17

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

5 Likes
18

I have opened Define copy for immutable values · Issue #45143 · JuliaLang/julia · GitHub to discuss this issue. I think it is safe to define copy for immutable values as identity.

6 Likes
19

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?

20

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 )

You can find more examples in the current code:

21

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.