Add docstrings for names, size, and order

[ajwheeler]

closes #1265 unless I'm mistaken

[bkamins]

Thank you for looking into it. I will give general comments as they apply to all docstrings to improve their consistency (I know not all docstrings strictly follow these recommendations, but for the future we should try to be consistent):

• please use docstring formatting recommended in Base, i.e. first line should start with the signature, separate example with ### Examples header
• please make sure that you document all relevant types, DataFrameRow in particular
• an appropriate entry to docs/src/lib/functions.md should be added for each documented function

[bkamins]

Please quote code in the text. Also it would be better if example were runnable. Finally if a function accepts some arguments they should be documented.

[ajwheeler]

You are referring to the kwargs of order, correct? Are there any besides rev? I was a bit confused by the source.

[ajwheeler]

Any by "runnable", do you mean that it should avoid undefined variables?

[bkamins]

In the body of ordering(col_ord::UserColOrdering, lt::Function, by::Function, rev::Bool, order::Ordering) you have a list of accepted kwargs.

By "runnable" I mean that when we enable docstring testing during CI (which we plan in the future) the code should run without error (as otherwise CI will fail). In this case it means that the use of undefined variable. The additional benefit of ensuring "runnability" is that the user can copy-paste the code and test what it does.

[ajwheeler]

Thanks for the notes. I'm not sure what you're referring to RE DataFrameRow. Could you spell that out for me? I don't see the connection to any of these methods.

[bkamins]

DataFrameRow is a type defined by DataFrames.jl and it is exported. It supports size and names functions so it would be good to add appropriate docstrings in src/dataframerow/dataframerow.jl. Thank you!

[nalimilan]

Thanks!

We should really clean our docstrings to follow the recommendations at https://docs.julialang.org/en/latest/manual/documentation/. For now I'd say it's OK to be consistent with our current style.

[bkamins]

@ajwheeler - after this is merged I can do what @nalimilan proposes above, but maybe you would be interested in doing this?

[ajwheeler]

Sorry, I no longer have time to work on this. Feel free to discard what I've done if it's easier.

…

On Sat, Jun 8, 2019 at 12:34 PM Bogumił Kamiński ***@***.***> wrote: @ajwheeler <https://github.com/ajwheeler> - after this is merged I can do what @nalimilan <https://github.com/nalimilan> proposes above, but maybe you would be interested in doing this? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1814?email_source=notifications&email_token=AAFN2GYHQDUHR46C2CWJWZLPZPNQXA5CNFSM4HNZQ5A2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXHYCZY#issuecomment-500138343>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAFN2GYYUW6EXDGGSKHMUD3PZPNQXANCNFSM4HNZQ5AQ> .

[bkamins]

@nalimilan - you are better with docstrings than me 😄 . How do you advise to proceed with this?

[bkamins]

I have opened #2077 instead of this PR.