API Docs: env

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/env/

• iterators should use the standard iterator boilerplate like https://doc.rust-lang.org/std/iter/struct.Map.html, this applies to all structs except for JoinPathsError
• JoinPathsError should properly link the function it comes from and use language similar to https://doc.rust-lang.org/std/io/struct.Error.html
• same wording issues with VarError
• functions need to ensure linkage to things they refer to in their descriptions

[GuillaumeGomez]

Seems the docs are all good here.

[steveklabnik]

There's still a bunch to do here; the module documentation is very sparse, not everything has examples, not all types are linked correctly.

[GuillaumeGomez]

I'll try to look for the missing ones then.

[steveklabnik]

I am happy to mentor anyone who wants to tackle this issue.

[mp4096]

I'd like to work on this one. Here are some ideas:

• Hoist some examples (e.g. using env vars or command line args) to the module-level documentation
• Explain the difference between os and non-os structs and methods
• Add explanation text for example snippets

@steveklabnik Maybe you have more ideas for a checklist? Thanks!

[steveklabnik]

@mp4096 ah yes, I don't know how I missed this one for the checklist! Those all seem like good changes. Ill try to come up with my own list sometime soonish, but until then, PRs for any/all of those things would be great 👍

[maccoda]

I wouldn't mind lending a hand here either.
@mp4096 what have managed to tackle? Don't want to step on your toes here 😄

[mp4096]

TBH I'm having a block here. Help would be greatly appreciated!

[maccoda]

Alright let's give this a go then 👍
@mp4096 if you don't mind I might try some of the points you raised as I think they would greatly help!
@steveklabnik when you are talking about the Iterator boilerplate, what exact part of that link are you referring to?

[steveklabnik]

@steveklabnik when you are talking about the Iterator boilerplate, what exact part of that link are you referring to?

This text:

An iterator that maps the values of iter with f.

This struct is created by the map() method on Iterator. See its documentation for more.

See these iterators for example:

• https://doc.rust-lang.org/stable/std/iter/struct.Filter.html
• https://doc.rust-lang.org/stable/std/iter/struct.FlatMap.html
• https://doc.rust-lang.org/stable/std/iter/struct.Peekable.html
• https://doc.rust-lang.org/stable/std/iter/struct.Rev.html

[maccoda]

Perfect. Thank you.

[steveklabnik]

Moving to p-high and assigning myself; i'd like to get this resolved in the next release cycle.

@mp4096 @maccoda I would still love your help if you have the time, but no worries if you don't!

[maccoda]

@steveklabnik I am definitely keen to help close this off. What points are remaining to be addressed?

[steveklabnik]

Hey @maccoda , thanks for all the stuff you've done so far 😄

• Args and ArgsOs need the iterator boilerplate still.
• I just noticed a missing period with SplitPaths, after 'function': This structure is created by the std::env::split_paths function See its documentation for more.

That actually looks like it, I think you got the rest of them! Do you want to knock those out?

[maccoda]

No worries at all @steveklabnik.

Easy done I will target to get them done by the end of the the weekend! 😄

[maccoda]

@steveklabnik I am just looking at the Args and ArgsOs documentation and I think the only part missing is the See its documentation for more., does that sound right to you?

This what we currently have for Args

An iterator over the arguments of a process, yielding a String value for each argument.

This structure is created through the std::env::args function.

This appears to have the general boilerplate for the remaining aspects I believe of:

1. Describe what type of iterator it is

   An iterator over the arguments ...

2. State how this iterator type is able to be obtained

   This structure is created through the std::env::args function.

[steveklabnik]

I think the only part missing is the See its documentation for more., does that sound right to you?

Yeah, basically I really like the consistency of having the exact same language everywhere. So a sort of "template" is

An iterator that {what it does}.

This struct is created by the {foo} method[ on {trait}]. See its documentation for more.

where the on trait bit is optional, filling in the rest between the {}s. Make sense?

So it'd be turning

This structure is created through the std::env::args function.

into

This struct is created by the std::env::args function. See its documentation for more.

This is extremely nitpicky, but I think this kind of detail-oriented polish takes the docs from 👍 to 💯

[maccoda]

No this is good, always easier to produce good documentation when there is a template. Will have to note this one down somewhere to remember 😄

[steveklabnik]

Will have to note this one down somewhere to remember 😄

We do need better docs for writing docs.... ha!

[maccoda]

Haha! Been keeping a reference for myself! 😄

[steveklabnik]

This was closed by #42579