Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added "Provide hints to similar functions" #23788

Merged
merged 8 commits into from
Sep 25, 2017
Merged

Added "Provide hints to similar functions" #23788

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5c552f3
Added "Provide hints to similar functions"
Sep 20, 2017
bc57c0d
added ms-list formatting, ref-links
Sep 20, 2017
5c872be
Removed short description style
Sep 20, 2017
c4a405b
Added frederiks corrections
Sep 20, 2017
172a528
whitespace
fredrikekre Sep 20, 2017
bb43799
Bold `See also`, add newline, wording suggestions
Sep 21, 2017
2124d89
Removed bold
Sep 25, 2017
c20f02d
fix colon
KristofferC Sep 25, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions doc/src/manual/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Sometimes there are functions of related functionality. To increase discoverability please provide
a short list of these in a `See also: ` section.

```
See also: [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@nalimilan nalimilan Sep 20, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

```
6. Include any code examples in an `# Examples` section.

Examples should, whenever possible, be written as *doctests*. A *doctest* is a fenced code block
(see [Code blocks](@ref)) starting with ````` ```jldoctest````` and contains any number of `julia>`
Expand Down Expand Up @@ -127,13 +135,13 @@ As in the example above, we recommend following some simple conventions when wri
!!! tip
Wherever possible examples should be **self-contained** and **runnable** so that readers are able
to try them out without having to include any dependencies.
6. Use backticks to identify code and equations.
7. Use backticks to identify code and equations.

Julia identifiers and code excerpts should always appear between backticks ``` ` ``` to enable
highlighting. Equations in the LaTeX syntax can be inserted between double backticks ``` `` ```.
Use Unicode characters rather than their LaTeX escape sequence, i.e. ``` ``α = 1`` ``` rather
than ``` ``\\alpha = 1`` ```.
7. Place the starting and ending `"""` characters on lines by themselves.
8. Place the starting and ending `"""` characters on lines by themselves.

That is, write:

Expand All @@ -156,7 +164,7 @@ As in the example above, we recommend following some simple conventions when wri
```

This makes it more clear where docstrings start and end.
8. Respect the line length limit used in the surrounding code.
9. Respect the line length limit used in the surrounding code.

Docstrings are edited using the same tools as code. Therefore, the same conventions should apply.
It it advised to add line breaks after 92 characters.
Expand Down