docs: return values don't show up in docs

[MarcoGorelli]

edit by @marenwestermann

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.

Note: There are a few functions/ methods where the documentation of the arguments is missing too. It would be great if you could add this too in case it's missing.

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

• series.py
  Series

  • abs
  • alias
  • all
  • any
  • arg_true
  • cast
  • clip
  • count
  • cum_count
  • cum_max
  • cum_min
  • cum_prod
  • cum_sum
  • diff
  • drop_nulls
  • dtype
  • fill_null
  • filter
  • gather_every
  • head
  • is_between
  • is_duplicated
  • is_empty
  • is_first_distinct
  • is_in
  • is_last_distinct
  • is_null
  • is_sorted
  • is_unique
  • item
  • len
  • max
  • mean
  • median
  • min
  • mode
  • n_unique
  • name
  • null_count
  • pipe
  • quantile
  • rename
  • replace_strict
  • round
  • sample
  • scatter
  • shape
  • shift
  • sort
  • std
  • sum
  • tail
  • to_arrow
  • to_dummies
  • to_frame
  • to_list
  • to_numpy
  • to_pandas
  • unique
  • value_counts
  • zip_with

  SeriesCatNamespace

  • get_categories

  SeriesStringNamespace

  • contains
  • ends_with
  • head
  • len_chars
  • replace
  • replace_all
  • slice
  • starts_with
  • strip_chars
  • tail
  • to_datetime
  • to_lowercase
  • to_uppercase

  SeriesDateTimeNamespace

  • convert_time_zone
  • date
  • day
  • hour
  • microsecond
  • millisecond
  • minute
  • month
  • nanosecond
  • ordinal_day
  • replace_time_zone
  • second
  • timestamp
  • to_string
  • total_microseconds
  • total_milliseconds
  • total_minutes
  • total_nanoseconds
  • total_seconds
  • year

[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!

[MarcoGorelli]

I've done the ones in expr.py as a lot of them weren't really obvious (e.g. a newcomer would not know what to expect the return type of nw.all to be) - we're getting a lot more interest in Narwhals recently so I think it's important for those to be accurate

The rest we can do at the sprint - thanks @marenwestermann for listing all the ones that need doing! 🙏

[marenwestermann]

Yeah, I was also thinking that the ones in expr.py might potentially be a bit (too) hard for newcomers. I'll update the list accordingly then (I saw that you already removed expr.py from the list but the ones for Series for example still need documentation).