JuliaLang/julia

Explicitly document the `missing` behavior for all functions that handle `missing` values

开放

#45,142 创建于 2022年5月1日

 (3 条评论) (0 个反应) (0 位负责人)Julia (5,773 个派生)batch import
docsgood first issue

仓库指标

星标
 (48,709 个星标)
PR 合并指标
 (PR 指标待抓取)

描述

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.

贡献者指南