DOCSP-30557: FAQ #102

norareidy · 2023-12-21T20:47:52Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-30557
Staging - https://preview-mongodbnorareidy.gatsbyjs.io/rust/DOCSP-30557-faq/faq/

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

ccho-mongodb

Plenty of helpful information here!

I left some comments mainly on making sure the information presented is clearly explained. Let me know if you have any questions.

source/faq.txt

ccho-mongodb

Added a few more suggestions and issues, but otherwise LGTM. If you would like me to take another look after making updates, let me know!

ccho-mongodb · 2024-01-05T04:10:34Z

source/faq.txt

+conversions between custom Rust types and BSON. You can install the ``serde``
+crate to access the functionality of the Serde framework. For instructions
+on installing this crate, see `serde <https://crates.io/crates/serde>`__ in the
+crates registry.


Suggestion:

I think it would be helpful to stay consistent with the terminology (whether "add the crate" or "install"). Based on
the prior comment and the first sentence of the next paragraph, perhaps this should be "add the crate".

ccho-mongodb · 2024-01-05T04:20:24Z

source/faq.txt

+
+After you add the crate to your application, you can model the documents in a collection
+by using a custom type instead of a BSON document. The following example includes a ``derive``
+statement before the ``Vegetable`` struct definition, which instructs the driver to


Suggestion:
From the Derive page in Rust by Example, it seems like "derive" should be an "attribute" rather than "statement".

good point - will fix in other Rust docs too

ccho-mongodb · 2024-01-05T04:26:12Z

source/faq.txt

+- ``Ok(T)``, which wraps the value of the result of the operation
+- ``Err(E)``, which wraps an error value if the operation is unsuccessful


Issue:

The style guide on List Items provides specific guidance on list items that separate the initial term and information about it:

If you need to separate the initial term or phrase from the information that follows it, use a colon. However, if you don't need a separator, don't use one. (For an example of a list in which separators aren't necessary, see the list at the top of this topic.

Suggestion:

Suggested change

- ``Ok(T)``, which wraps the value of the result of the operation

- ``Err(E)``, which wraps an error value if the operation is unsuccessful

- ``Ok(T)``: wraps the value of the result of the operation if the operation is successful

- ``Err(E)`: wraps an error value if the operation is unsuccessful

Applies to all similar instances.

ccho-mongodb · 2024-01-05T04:31:18Z

source/faq.txt

+To access the result of ``insert_one()``, you can use the ``?`` operator to unwrap its
+return value. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult``


Suggestion:

I think the first part of the sentence should directly introduce the rest of the sentence

In the current sentence, the first part mentions accessing the result and the rest of it explains only how to unwrap the return value.

Suggested change

To access the result of ``insert_one()``, you can use the ``?`` operator to unwrap its

return value. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult``

To access the unwrapped result of ``insert_one()``, use the ``?`` operator. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult``

source/faq.txt

ccho-mongodb · 2024-01-05T04:43:33Z

source/faq.txt

+Alternatively, you can create custom logic for handling the ``InsertOneResult`` value
+depending on whether ``insert_one()`` returns the value wrapped in the ``Ok`` or the ``Err``
+variant. The following code uses the ``match`` keyword to process the ``insert_one()``


Suggestion:

No change necessary, but I think this might be a more succinct way to present this sentence since Result (InsertOneResult, once that equivalence is added) was explained earlier:

Suggested change

Alternatively, you can create custom logic for handling the ``InsertOneResult`` value

depending on whether ``insert_one()`` returns the value wrapped in the ``Ok`` or the ``Err``

variant. The following code uses the ``match`` keyword to process the ``insert_one()``

Alternatively, you can create a conditional to handle the unwrapped values of ``InsertOneResult``. The following code uses the ``match`` keyword to process the ``insert_one()``

ccho-mongodb · 2024-01-05T04:47:33Z

source/faq.txt

+- `Result <https://doc.rust-lang.org/std/result/enum.Result.html>`__
+- `Option <https://doc.rust-lang.org/std/option/enum.Option.html>`__
+- `? Operator <https://doc.rust-lang.org/rust-by-example/std/result/question_mark.html>`__
+- `If Let <https://doc.rust-lang.org/book/ch06-03-if-let.html>`__


Suggestion:

I think this could be confusing since the keywords "if" and "let" are lowercase in their usage and the content of the link describes behavior of using two keywords in a pattern rather than adjacent to each other:

Suggested change

- `If Let <https://doc.rust-lang.org/book/ch06-03-if-let.html>`__

- Control Flow with `if let <https://doc.rust-lang.org/book/ch06-03-if-let.html>`__

ccho-mongodb · 2024-01-05T04:49:46Z

source/faq.txt

+The ``Option`` enum can return the following variants:
+
+- ``None``, which represents an empty value returned by an operation
+- ``Some(T)``, which wraps a nonempty return value


Suggestion:

I think "nonempty" is usually spelled with a hyphen ("non-empty").

Suggestion:

I think the placement of the Result example directly after this makes it awkward. Instead, perhaps placing this before the line that starts with "Some {+driver-short+} methods return an Option type, such as the read_concern()..." would make the information more organized and easier to locate.

ccho-mongodb · 2024-01-05T04:52:16Z

source/faq.txt

+   }
+
+You can then create a ``Collection`` instance with your custom struct type as its
+generic type parameter. The following example instantiates the ``my_coll`` collection


Suggestion:

I think lowercase collection might imply a collection name rather than the Collection struct.

Suggested change

generic type parameter. The following example instantiates the ``my_coll`` collection

generic type parameter. The following example instantiates the ``my_coll`` Collection

Alternatively, perhaps "variable" would be more conventional since this describes assignment rather than direct instantiation.

(cherry picked from commit bd90347)

norareidy added 4 commits December 21, 2023 15:47

adding content

5dac54b

edits + build

390d416

fixes

00961bb

vale

6612159

ccho-mongodb suggested changes Jan 2, 2024

View reviewed changes

norareidy added 3 commits January 3, 2024 15:57

CC feedback

0d5dcc9

small edits

e2409c7

adding some stuff

9767f88

norareidy requested a review from ccho-mongodb January 3, 2024 21:20

ccho-mongodb approved these changes Jan 5, 2024

View reviewed changes

norareidy added 3 commits January 5, 2024 14:57

CC feedback 2

2f16139

edits

4cedd22

small thing

f53229a

kevinAlbs requested a review from isabelatkinson January 5, 2024 21:35

isabelatkinson approved these changes Jan 9, 2024

View reviewed changes

norareidy merged commit bd90347 into mongodb:master Jan 9, 2024

norareidy deleted the DOCSP-30557-faq branch January 9, 2024 18:54

norareidy added a commit that referenced this pull request Jan 9, 2024

DOCSP-30557: FAQ (#102)

d560197

(cherry picked from commit bd90347)

norareidy added a commit that referenced this pull request Jan 9, 2024

DOCSP-30557: FAQ (#102)

0f54ebd

(cherry picked from commit bd90347)

		- ``Ok(T)``, which wraps the value of the result of the operation
		- ``Err(E)``, which wraps an error value if the operation is unsuccessful

		To access the result of ``insert_one()``, you can use the ``?`` operator to unwrap its
		return value. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult``

	To access the result of ``insert_one()``, you can use the ``?`` operator to unwrap its
	return value. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult``
	To access the unwrapped result of ``insert_one()``, use the ``?`` operator. If the operation is successful, the ``?`` operator unwraps the ``InsertOneResult``

	- `If Let <https://doc.rust-lang.org/book/ch06-03-if-let.html>`__
	- Control Flow with `if let <https://doc.rust-lang.org/book/ch06-03-if-let.html>`__

	generic type parameter. The following example instantiates the ``my_coll`` collection
	generic type parameter. The following example instantiates the ``my_coll`` Collection

DOCSP-30557: FAQ #102

DOCSP-30557: FAQ #102

Uh oh!

Conversation

norareidy commented Dec 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Self-Review Checklist

Uh oh!

ccho-mongodb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ccho-mongodb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

norareidy commented Dec 21, 2023 •

edited

Loading