JuliaLang/julia

Include all public docstrings in the manual

Open

#19,529 opened on Dec 7, 2016

View on GitHub
 (8 comments) (2 reactions) (0 assignees)Julia (48,709 stars) (5,773 forks)batch import
docsdocsystemhelp wanted

Description

Currently there are a significant number (200+) docstrings in Base and it's submodules that are not included in the manual anywhere. To see the current list of docstrings that still need to be included change the following line in doc/make.jl

    checkdocs = :none,

to

    checkdocs = :all,

and build the docs with

make docs

from the root directory.

There's some docstrings for names that are exported and should definitely find there way into the manual somewhere, as well as quite a few internal docstrings that probably don't need to be included or could do with some improvements before inclusion.

(I'm marking this issue as up-for-grabs since it can readily be distributed between many contributors.)

Contributor guide

Tech stack
None
Domain
documentation
Issue type
documentation
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-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
Basic Julia knowledgeAbility to build Julia documentation from source
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75
Research direction
Begin by modifying the file `doc/make.jl` to set `checkdocs = :all` instead of `:none`, then build the documentation using `make docs` from the root directory. This will generate a list of all docstrings not currently included in the manual. For each docstring, determine whether it is exported (public) and should be added to the appropriate manual page. For internal docstrings, assess if they need revision or can be omitted. The issue is marked as up for grabs, so contributors can focus on a subset of docstrings. Review any existing comments for guidance on which docstrings to prioritize.
Include all public docstrings in the manual · JuliaLang/julia#19529 | Good First Issue