Crystal: feature request: API docs providing single example

[vectorselector]

Hello, I'm not sure if this is an appropriate place or manner to submit feature requests.

While trying to learn to use Process.run, for example, I encounter the following notation, which I am aware is typed-notation in a technical specification of some kind.

def self.run(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : Stdio = Redirect::Close, output : Stdio = Redirect::Close, error : Stdio = Redirect::Close, chdir : String? = nil) : Process::Status

for example.

I think it would be a HUGE usability plus to have a singular actual Crystal code example per method for API documentation.
I'm not sure how changes to API code is integrated. I would be happy to provide some examples for methods I already know, although I'm not sure where vetting/correction of mistakes would occur, process wise.

If I'm being out-of-order here, please kindly inform me and I can close this issue and follow your preferred processes.
Thank you for your attention on this topic.

[jhass]

API level documentation lives directly in the source code. For your example, here: https://github.com/crystal-lang/crystal/blob/d91a6386f8626bebba146614773d5cb6bc3c33f7/src/process.cr#L126-L128

Pull requests to improve these are always welcome. We have no policy I'm aware of that would reject adding an example to each one. Note however there's a project coming by every couple of weeks that automatically evaluates them and checks the example results given still are accurate, for this to work the examples need to be a fully functional and self contained Crystal program.

[vectorselector]

thank you, @jhass
I'll close this, and start adding a few examples here and there with the advice you give about being self-contained and fully functional Crystal code for passing this evaluating project you mention.

[vectorselector]

I do have one question, however.
How do you suggest that I integrate the example?

`#would it be wrong to use comments

or should I extend the object or?`

[Blacksmoke16]

@vectorselector I'd read thru https://crystal-lang.org/reference/conventions/documenting_code.html if you haven't already.

[jhass]

Yes, please see the document above (I always forget about it 🙈). Also a lot of documentation already has examples, feel free to get inspiration from there :)

[vectorselector]

Hmmm, I now feel a bit stupid. Isn't this precisely done in the spec for std?
for example, https://github.com/crystal-lang/crystal/blob/master/spec/std/process_spec.cr

I guess I should never have created this issue!

What is a good way to begin helping with Crystal?

[jhass]

No, the specs are not used for any documentation purposes :)

[straight-shoota]

Specs are only for internal use. In case there are no examples in the docs, they may certainly be worht a look. But they are not part of the API docs and our goal should be to have usage examples in the API docs.
Because of the similar nature, specs often serve as a good insipration for API doc examples.

Best way to help improving this is to edit for example src/process.cr and add usage examples for methods where they're missing. And maybe also improve the method description if necessary.

[z64]

This is somewhat tangential, but a lot of languages offer doctests, either as part of the standard toolchain or libraries - Python, Elixir, Rust, Julia, to name a few - ensuring all code examples in documentation compile. For some of those languages, "1 doc test per method" is part of its testing/documentation culture. It would be great to see that in Crystal someday.

[jhass]

Not a core team effort, but this is what https://github.com/maiha/crystal-examples is doing.

[z64]

@jhass Oh cool, thank you for bringing that to my attention! ❤️

[vectorselector]

@straight-shoota

Best way to help improving this is to edit for example src/process.cr and add usage examples for methods where they're missing. And maybe also improve the method description if necessary.

would usage examples be valid crystal code but in comments, per the style guide @jhass told me about? https://crystal-lang.org/reference/conventions/documenting_code.html

or, would they be in a separate class/object that requires the module we wish to demonstrate the methods usage, in a similar manner like the specs? (but inside the src/process.cr for example)

or what's the preferred way to add usage examples so as to benefit the auto-generated docs per
crystal docs

[straight-shoota]

Yes, usage examples should be embedded in the doc comment. As mentioned in the documentation guide, code blocks are simply enclosed in triple backticks.

An example from process.cr:

https://github.com/crystal-lang/crystal/blob/dbf2a21e76c45b369fb69a948065fc550fae989b/src/process.cr#L414-L416

You can look at other source files to get inspiration on how to write such examples. enumerable.cr for example has lots of them.

[vectorselector]

Thank you @straight-shoota .
One more question, sorry :D
documentation examples like this should be in which git branch?
is it best to make individual additions of examples per edit? PR?
any "best practices" on this repo?

[jhass]

I would generally not touch (documentation for) more than one broader standard library feature (say Process and Array) per pull request.

Smaller pull requests get reviewed and merged faster, but cause more maintenance overhead on your end since they're more likely to get out of date or conflicted when you submit multiple in the same area of code. See https://github.blog/2020-05-21-github-protips-tips-tricks-hacks-and-secrets-from-sarah-vessels/ for an interesting read on this.

[straight-shoota]

It's perfectly fine to edit documentation for different related features (for example Process and its methods) in a single PR. Whether you split them into individual commits or not doesn't really matter. They'll be squashed on merge anyway.