Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Method examples for Result and Option #17339

Merged
merged 5 commits into from Sep 22, 2014

Conversation

Projects
None yet
3 participants
@treeman
Copy link
Contributor

treeman commented Sep 17, 2014

Also some cleanup to conform to documentation style.

treeman added some commits Sep 16, 2014

doc: Cleanup.
Remove ~~~ for code block specification. Use /// Over /** */ for doc
blocks.
@@ -270,6 +326,18 @@ impl<T> Option<T> {
/// In general, because this function may fail, its use is discouraged.
/// Instead, prefer to use pattern matching and handle the `None`
/// case explicitly.
///
/// # Examle

This comment has been minimized.

@steveklabnik

steveklabnik Sep 17, 2014

Member

should be "Example" 😄

Idents bound to the variant index values for each of the actual
input Self arguments.
*/
/// non-matching variants of the enum, but with all state hidden from

This comment has been minimized.

@steveklabnik

steveklabnik Sep 17, 2014

Member

Non-matching

/// the Self arguments; the second component is a slice of all of the
/// variants for the enum itself, and the third component is a list of
/// Idents bound to the variant index values for each of the actual
/// input Self arguments.

This comment has been minimized.

@steveklabnik

steveklabnik Sep 17, 2014

Member

The Ident and Selfs here should have backticks.

all the fields of all the structures, see above for details.
*/
/// Combine the values of all the fields together. The last argument is
/// all the fields of all the structures, see above for details.

This comment has been minimized.

@steveklabnik

steveklabnik Sep 17, 2014

Member

I would say 'above' isn't clear here. I know you're just fixing formatting though, so it's not the worst thing...

This comment has been minimized.

@treeman

treeman Sep 17, 2014

Author Contributor

I actually removed the references. I guess I could expand on 'above' instead, but then that should be added to a couple more places. I think it's fair to search out the documentation for the root level without having to specify it?

/// identifiers (one for each Self argument, which could be any of the
/// variants since they have been collapsed together) and the identifiers
/// holding the variant index value for each of the Self arguments. The
/// last argument is all the non-Self args of the method being derived.

This comment has been minimized.

@steveklabnik

steveklabnik Sep 17, 2014

Member

Same here, Self could use backticks.

/// 'z, A, ..., Z>`, creates an impl like:
///
/// ```ignore
/// impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T<A, ..., Z> { ... }

This comment has been minimized.

@steveklabnik

steveklabnik Sep 17, 2014

Member

this doesn't need indenting.

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Sep 17, 2014

Thanks for this! one other comment: do we need the leading .s in the directives?

treeman added some commits Sep 17, 2014

@treeman

This comment has been minimized.

Copy link
Contributor Author

treeman commented Sep 17, 2014

We do not actually need the .s. Is it preferred to use the shorter form? I see the {.rust} format in a lot of places.

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Sep 17, 2014

Currently, I've been using {rust} everywhere, but we don't have an official style on this, and I'm actually not sure that it's worth being explicit.

Do you want to maybe collaborate on some kind of doc style guide RFC? /cc @aturon

@treeman

This comment has been minimized.

Copy link
Contributor Author

treeman commented Sep 17, 2014

I could collaborate on something like that yeah.

@treeman

This comment has been minimized.

Copy link
Contributor Author

treeman commented Sep 21, 2014

r?

@bors

This comment has been minimized.

Copy link
Contributor

bors commented on a0d502b Sep 22, 2014

This comment has been minimized.

Copy link
Contributor

bors replied Sep 22, 2014

merging treeman/rust/doc-things = a0d502b into auto

This comment has been minimized.

Copy link
Contributor

bors replied Sep 22, 2014

treeman/rust/doc-things = a0d502b merged ok, testing candidate = 8a45818

This comment has been minimized.

Copy link
Contributor

bors replied Sep 22, 2014

fast-forwarding master to auto = 8a45818

bors added a commit that referenced this pull request Sep 22, 2014

auto merge of #17339 : treeman/rust/doc-things, r=alexcrichton
Also some cleanup to conform to documentation style.

@bors bors closed this Sep 22, 2014

@bors bors merged commit a0d502b into rust-lang:master Sep 22, 2014

1 of 2 checks passed

continuous-integration/travis-ci The Travis CI build failed
Details
default all tests passed

@treeman treeman deleted the treeman:doc-things branch Sep 22, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.