JuliaLang/julia

Show similar functions in docstrings

Open

#23763 opened on Sep 19, 2017

View on GitHub
 (3 comments) (3 reactions) (0 assignees)Julia (48,709 stars) (5,773 forks)batch import
docsgood first issuehelp wanted

Description

I think discoverability would be greatly enhanced, if there would be some hints at similar functions in the docstrings. I imagine a line of See also: ...function names... which should be generated from a table of related functions automatically.

This came to my mind when looking at the docs of pop!. The functions shift! and splice! offer solutions to similar problems, but their names cannot be guessed from each other.

pop!(collection, key[, default])

  Delete and return the mapping for key if it exists in collection, otherwise return default, or
  throw an error if default is not specified.

[...]

See also: shift!(), splice!()

Of course, the wording is open for bike shedding 👍

Contributor guide

Tech stack
None
Domain
documentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
None
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
40
Research direction
The issue requests adding a 'See also' line to docstrings, linking to similar functions like shift! and splice!. To implement, one would need to identify where documentation strings are generated in Julia's base library, likely in the 'Base' module. Investigate existing doc generation code in files like 'base/docs.jl' or similar. The proposal is to create a table of related functions and automatically include references. The implementation may involve modifying the doc system to read a mapping and append cross references. No maintainer response is visible, but the idea is straightforward. Start by examining how current docstrings are produced and find where to inject the new line.