docs: return values don't show up in docs

[MarcoGorelli]

edit by @marenwestermann [WIP]

Add a "Returns" section to the doc strings of functions and methods which concisely describes what is being returned.
Start with one or two functions at a time. Once you feel familiar with the documentation process you can update several functions at a time (remember to ideally keep your pull requests small). For more details and an example see below.

List of functions/ methods that need the "Returns"documentation:

• dataframe.py
  DataFrame:

  • lazy
  • to_pandas
  • write_csv
  • write_parquet
  • to_numpy
  • shape
  • get_column
  • to_dict
  • row
  • pipe
  • drop_nulls
  • with_row_index
  • schema
  • collect_schema
  • columns
  • rows
  • iter_rows
  • select
  • rename
  • head
  • tail
  • drop
  • unique
  • filter
  • sort
  • is_duplicated
  • is_empty
  • is_unique
  • null_count
  • item
  • clone
  • gather_every
  • to_arrow
  • sample
  • unpivot

  LazyFrame

  • pipe
  • drop_nulls
  • with_row_index
  • schema
  • collect_schema
  • columns
  • select
  • rename
  • head
  • tail
  • drop
  • filter
  • group_by
  • sort
  • clone
  • lazy
  • gather_every
  • unpivot

• expr.py
  Expr

  • Expr
  • alias
  • pipe
  • cast
  • any
  • all
  • mean
  • median
  • std
  • map_batches
  • sum
  • min
  • max
  • count
  • n_unique
  • unique
  • abs
  • cum_sum
  • diff
  • shift
  • replace_strict
  • sort
  • is_between
  • is_in
  • filter
  • is_null
  • arg_true
  • fill_null
  • drop_nulls
  • sample
  • over
  • is_duplicated
  • null_count
  • is_first_distinct
  • is_last_distinct
  • quantile
  • head
  • tail
  • round
  • len
  • gather_every
  • clip
  • mode

[MarcoGorelli]

we can resolve this by adding a Returns section, which will then pick up on the type annotations:

e.g. for from_dict:

    Returns:
        DataFrame

[marenwestermann]

I can start working on this one. Just for clarification:

• this should be done for all public functions that are exposed to the user, right?
• you follow the Google docstring format, correct? Edit: found the specification in the pyproject.toml file 😊

[MarcoGorelli]

wonderful, thanks!

yes, that's right!