narwhals-dev / narwhals

Lightweight and extensible compatibility layer between dataframe libraries!
https://narwhals-dev.github.io/narwhals/
MIT License
611 stars 91 forks source link

docs: bikeshed on good name for example function in docs #1407

Closed MarcoGorelli closed 2 days ago

MarcoGorelli commented 6 days ago

Related to https://github.com/narwhals-dev/narwhals/pull/1406#issuecomment-2486295148

Currently the docstring examples of use func or my_library_agnostic_function

Let's discuss on Friday's call what to name the functions

In the meantime I'm pretty keen on not having narwhalify in the docstrings, so we can showcase type annotations and keep things simple and non-magical for newcomers

FBruzzesi commented 6 days ago

This would be much more effort, yet in my opinion a descriptive function name would be related to the method it performs.

E.g. for Series.value_counts method, in the docstring example something along the lines of

def agnostic_value_counts(s_native):
    ...

would be descriptive for me.

Of course if we manage to find some unique and appealing name that would be grand!