JuliaLang/julia

Show similar functions in docstrings

Open

#23,763 opened on Sep 19, 2017

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

Repository metrics

Stars
 (48,709 stars)
PR merge metrics
 (Avg merge 20d 6h) (157 merged PRs in 30d)

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

Research direction
Investigate how docstrings are generated in Julia and propose a method to add automatic cross references to similar functions.
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.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Mostly clear
Prerequisites
None
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65