Explicitly document the `missing` behavior for all functions that handle `missing` values · JuliaLang/julia#45142

(3 comments) (0 reactions) (0 assignees)Julia (48,709 stars) (5,773 forks)batch import

docsgood first issue

Description

I think that every function that handles missing values should have its handling of missing values documented in its docstring. There are two possible ways to do this:

Add discussion of the handling of missing values to the generic foo(x) docstring.
Add separate docstrings for all the foo(::Missing), bar(::Missing, ::Any), etc, methods.
- This approach won't work for methods that take iterators, like all, any, maximum, and minimum.

Functions that handle missing values currently do not have fully specified APIs, since their docstrings make no mention of missing values. My position is that docstrings should always strive to fully specify the API of their functions, so that in theory a person could write an entire application by referring only to the docstrings. In other words, you shouldn't have to run foo(missing) in the REPL in order to determine whether foo handles missing values.

Contributor guide

Tech stack: None
Domain: documentation
Issue type: documentation
Difficulty: 2
Estimated time: half day
Activity status: stale
Clarity: clear
Prerequisites: Understanding of Julia's missing typeFamiliarity with docstring conventions
Newbie friendliness: 80
Research direction: Look at the Julia base library files (e.g., base/missing.jl) to identify all functions that handle missing values. Review the existing docstrings to see if missing behavior is already documented. Choose one of the two approaches described in the issue: either add missing value discussion to the generic docstring or add separate docstrings for missing methods. Implement the changes and ensure consistency across all functions.