Added "Provide hints to similar functions" #23788

ChristianKurz · 2017-09-20T06:34:25Z

This PR proposes a standard wording for hints to similar functions.
Feel free to correct and change!

#23763, #20531

This PR proposes a standard wording for hints to similar functions. Feel free to correct and change!

KristofferC · 2017-09-20T06:44:06Z

doc/src/manual/documentation.md

+   discoverability please provide a short list of these similar functions in a `See also: ` section.
+
+   ```
+   See also: bar!, baz, baaz


Perhaps write this as

See also: [`bar!`](@ref), [`baz`](@ref),

etc. This will cause the identifier to be quoted and a link to its documentation will be generated in the HTML.

KristofferC · 2017-09-20T06:45:31Z

doc/src/manual/documentation.md

+   in a list:
+
+   ```
+   See also: bar! - mutating variant, see for description of keyword arguments 


Are you sure this will render correctly?

fredrikekre · 2017-09-20T07:29:15Z

doc/src/manual/documentation.md

-5. Include any code examples in an `# Examples` section.
+5. Provide hints to similar functions
+
+   Sometimes there are functions of similar functionality, which are named quite different. To increase 


Perhaps similar functionality -> related functionality?
Also, which are named quite different is not needed; it is useful to list related functions even if they have similar names.

fredrikekre · 2017-09-20T07:30:15Z

doc/src/manual/documentation.md

+5. Provide hints to similar functions
+
+   Sometimes there are functions of similar functionality, which are named quite different. To increase 
+   discoverability please provide a short list of these similar functions in a `See also: ` section.


Perhaps: please provide a short list of these similar functions in a... -> please provide a short list of these in a ... to avoid duplication

fredrikekre · 2017-09-20T07:31:46Z

doc/src/manual/documentation.md

+   ```
+   See also: bar!, baz, baaz
+   ```
+   If the difference in functionality is not obvious from the name, you can provide a short description 


I don't like this second part. Docstrings should be distinct and describe the function, not describe other functions. If similar functions are listed it is easy enough to look up what they do.

I did not like that part either. I proposed this list as it seems to be common practice to refer other functions with a short description in docstrings:

Sort a multidimensional array A along the given dimension. See sort! for a description of possible keyword arguments.

shuffle([rng=GLOBAL_RNG,] v) Return a randomly permuted copy of v. The optional rng argument specifies a random number generator (see Random Numbers). To permute v in-place, see shuffle!. To obtain randomly permuted indices, see randperm.

Perhaps the better approach is to remove these redundant descriptions and just rely on the See also:-list

The difference is that the examples you listed here refer to more documentation about the documented function -- they don’t describe other functions.

At least the docstring to shuffle does:

To permute v in-place, see shuffle!. To obtain randomly permuted indices, see randperm.

And i think i have seen this pattern quite often.

Should we change those docs?

I think that can be decided from case to case, and those examples are probably there for a reason. I just don't think we should explicitly recommend that style, as suggested in this PR.

fredrikekre

Thanks!

mschauer · 2017-09-20T10:29:12Z

Note that there are often better alternatives to adding references under "See also".

Often the relationship can make explicit, "This function quit is equivalent to exit(0)" is better than "See also: exit".

Having a long list of see alsos indicates that there is an undocumented higher-level concept:
"RoundNearest is the default RoundingMode" is better than "See also: RoundNearest, RoundNearestTiesAway, RoundNearestTiesUp, RoundToZero, RoundFromZero, RoundUp, RoundDown"

(This is basically what the Wikipedia community figured out after some disagreements.)

nalimilan · 2017-09-20T11:59:23Z

doc/src/manual/documentation.md

+   discoverability please provide a short list of these similar functions in a `See also: ` section.
+
+   ```
+   See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref)


Maybe this should be a # section, just like # Examples?

I think a heading is a bit too verbose. # See also: pop!, shift! renders as

See also: pop!, shift! ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

I would rather bold **See also:** to add visibility.

I know, i called it section in the docs, which might be a bit confusing, if it's not rendered as a section...

I think there's a more general issue (even for # Examples) with the three lines which are too heavy (see #22870). So I'd rather use a consistent style with one section for "See also " and one section for "Examples", and fix both at the same time later. Note that the REPL isn't the only display format: there's also the HTML manual, where sections look much nicer (see screenshot at #22870).

Also, since you recommend to use a bullet list when describing functions, it's important to clearly separate it from the description of the function itself. So overall I suggest always having # See also section heading just like # Examples, and then always a line break, followed either by a list of functions on a single line, or list with bullet points.

EDIT: see also the argument made by @StefanKarpinski at #22870 (comment) regarding the semantic content of sections, as opposed to just using bold.

I don't think it should be a section like that, I think it could even just be the last sentence of the docstring:

push!(collection, items...) -> collection Insert one or more items at the end of collection. See also: `append!`, `pop!` # Examples [...]

IMO this should just be a tiny side note, definitely not as important as examples for the function.

OK, I see you dropped the suggestion to use a bullet list. Let's go with the lighter solution then, but at least add a line break before it. Also please remove the term "section" (maybe call it "paragraph").

nalimilan · 2017-09-20T15:32:22Z

doc/src/manual/documentation.md

@@ -81,7 +81,15 @@ As in the example above, we recommend following some simple conventions when wri
   ...
   """
   ```
-5. Include any code examples in an `# Examples` section.
+5. Provide hints to similar functions


Better use "related" here too. exp and log are definitely related, but I wouldn't consider them as "similar". Also missing ending period.

fredrikekre · 2017-09-21T08:08:32Z

doc/src/manual/documentation.md

+5. Provide hints to related functions.
+
+   Sometimes there are functions of related functionality. To increase discoverability please provide
+   a short list of these in a `**See also:**` paragraph.


I would prefer ditching the boldness here, it draws attention from the docstring.

right, the newline should be enough.

I updated the pop!, push! etc. docs to comply with these rules.
I kind of like the boldness better than the newline, though. Any further comments?

I don't have a strong opinion regarding the bold, but we probably don't need a new line after "See also". A line break before it should be enough IMHO.

I think the bold looks ugly. With a new line, you mean an empty line between the docstring and "See also" right? Just a new line won't render as a such.

julia> """ foo Calculate foo. See also: `bar` """ foo foo help?> foo search: floor pointer_from_objref OverflowError RoundFromZero FileMonitor functionloc StackOverflowError @functionloc Factorization OutOfMemoryError unsafe_pointer_to_objref default_worker_pool foo Calculate foo. See also: bar

vs

julia> """ foo Calculate foo. See also: `bar` """ foo foo help?> foo search: floor pointer_from_objref OverflowError RoundFromZero FileMonitor functionloc StackOverflowError @functionloc Factorization OutOfMemoryError unsafe_pointer_to_objref default_worker_pool foo Calculate foo. See also: bar

nalimilan · 2017-09-25T08:27:04Z

doc/src/manual/documentation.md

+   a short list of these in a `See also:` paragraph.
+
+   ```
+   See also:[`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref)


Missing space after :.

KristofferC · 2017-09-25T08:30:04Z

I fixed it the space. This LGTM now.

ChristianKurz · 2017-09-25T08:45:28Z

Thank you and sorry for making some less than helpful edits. I'm still new to this and i really should start editing files locally and not through the GitHub 'edit' feature...

fredrikekre · 2017-09-25T10:54:13Z

#23796 × 2

nalimilan · 2017-09-25T11:50:11Z

Thanks @Shorty66! Hopefully if you make more PRs they will be merged more quickly now that we have decided what conventions to follow.

"can I apply function to columns of a matrix or rows ? something like map..." I see this question asked a lot lately - so i think the best way is to hint at `mapslices` from the documentation of `map`. See [JuliaLang#23788]

"can I apply function to columns of a matrix or rows ? something like map..." I see this question asked a lot lately - so i think the best way is to hint at `mapslices` from the documentation of `map`. See [#23788]

Added "Provide hints to similar functions"

5c552f3

This PR proposes a standard wording for hints to similar functions. Feel free to correct and change!

ChristianKurz pushed a commit to ChristianKurz/julia that referenced this pull request Sep 20, 2017

Add See also: to pop!, shift! and splice!

c85de3b

JuliaLang#23788

ChristianKurz mentioned this pull request Sep 20, 2017

Add See also: , remove description of other functions in base.array.jl #23789

Closed

KristofferC reviewed Sep 20, 2017

View reviewed changes

fredrikekre reviewed Sep 20, 2017

View reviewed changes

Christian Kurz and others added 4 commits September 20, 2017 09:32

added ms-list formatting, ref-links

bc57c0d

Removed short description style

5c872be

Added frederiks corrections

c4a405b

whitespace

172a528

fredrikekre approved these changes Sep 20, 2017

View reviewed changes

nalimilan reviewed Sep 20, 2017

View reviewed changes

Bold See also, add newline, wording suggestions

bb43799

fredrikekre reviewed Sep 21, 2017

View reviewed changes

Removed bold

2124d89

nalimilan reviewed Sep 25, 2017

View reviewed changes

fix colon

c20f02d

KristofferC approved these changes Sep 25, 2017

View reviewed changes

nalimilan approved these changes Sep 25, 2017

View reviewed changes

fredrikekre approved these changes Sep 25, 2017

View reviewed changes

ChristianKurz closed this Sep 25, 2017

ChristianKurz reopened this Sep 25, 2017

fredrikekre merged commit ee7b0b8 into JuliaLang:master Sep 25, 2017

ChristianKurz mentioned this pull request Oct 13, 2017

hint to mapslices from map #24127

Merged

Seelengrab mentioned this pull request Oct 21, 2021

Show similar functions in docstrings #23763

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added "Provide hints to similar functions" #23788

Added "Provide hints to similar functions" #23788

ChristianKurz commented Sep 20, 2017

KristofferC Sep 20, 2017

KristofferC Sep 20, 2017

fredrikekre Sep 20, 2017

fredrikekre Sep 20, 2017

fredrikekre Sep 20, 2017

ChristianKurz Sep 20, 2017

fredrikekre Sep 20, 2017

ChristianKurz Sep 20, 2017

fredrikekre Sep 20, 2017

fredrikekre left a comment

mschauer commented Sep 20, 2017

nalimilan Sep 20, 2017

ChristianKurz Sep 20, 2017

nalimilan Sep 20, 2017 •

edited

Loading

fredrikekre Sep 20, 2017

nalimilan Sep 20, 2017

nalimilan Sep 20, 2017

fredrikekre Sep 21, 2017

ChristianKurz Sep 21, 2017 •

edited

Loading

nalimilan Sep 22, 2017

fredrikekre Sep 22, 2017

nalimilan Sep 25, 2017

KristofferC commented Sep 25, 2017

ChristianKurz commented Sep 25, 2017 •

edited

Loading

fredrikekre commented Sep 25, 2017

nalimilan commented Sep 25, 2017

Added "Provide hints to similar functions" #23788

Added "Provide hints to similar functions" #23788

Conversation

ChristianKurz commented Sep 20, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fredrikekre left a comment

Choose a reason for hiding this comment

mschauer commented Sep 20, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nalimilan Sep 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ChristianKurz Sep 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KristofferC commented Sep 25, 2017

ChristianKurz commented Sep 25, 2017 • edited Loading

fredrikekre commented Sep 25, 2017

nalimilan commented Sep 25, 2017

nalimilan Sep 20, 2017 •

edited

Loading

ChristianKurz Sep 21, 2017 •

edited

Loading

ChristianKurz commented Sep 25, 2017 •

edited

Loading