DOCSP-48381 make specify docs page

[shuangela]

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-48381
Staging - https://deploy-preview-1037--docs-node.netlify.app/crud/query/specify-documents-to-return/

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?

[netlify]

✅ Deploy Preview for docs-node ready!

Name	Link
🔨 Latest commit	7d55403
🔍 Latest deploy log	https://app.netlify.com/sites/docs-node/deploys/67eaac4b416f480008743b92
😎 Deploy Preview	https://deploy-preview-1037--docs-node.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[norareidy]

Nice work! I left some copy edits that aren't really in scope for this ticket, so feel free to ignore S: comments you don't think are necessary

[norareidy]

S: can't comment on lines 26-27 but since these are method names, I'd add () to the end of each

Suggested change

	- ``skip``: Specifies the number of documents to skip before returning query results.
	- ``skip()``: Specifies the number of documents to skip before returning query results.

[norareidy]

applies to all mentions of the skip(), sort(), limit() methods

[norareidy]

S: [nit] to avoid repeating follow/following

Suggested change

	To follow the examples in this guide, use the following code snippet to insert documents
	To run the examples in this guide, use the following code snippet to insert documents

[norareidy]

S:

Suggested change

	Use ``limit`` to cap the number of documents that can be returned from a read operation.
	Use the ``limit()`` method to cap the number of documents that can be returned from a read operation.

[norareidy]

S: a little more concise

Suggested change

	``limit`` functions as a cap on the maximum number of
	``limit`` specifies the maximum number of

[norareidy]

S: this might be outside the scope of this PR so optional, but I'd turn this code description into a bulleted list

[norareidy]

I: the previous example does specify these as parameters (an options parameter) to the find() method. Either you can show how to specify each as methods chained to find(), or omit this part

[norareidy]

I: this example is missing limit

[norareidy]

S:

Suggested change

	guide, see the following API Documentation:
	guide, see the following API documentation:

[norareidy]

S: you can use :ref: here instead of :doc:

[norareidy]

S: since these are just methods

Suggested change

	To learn more about any of the methods or types discussed in this
	To learn more about any of the methods discussed in this

[norareidy]

LGTM with final suggestions, let me know if you want me to take another look

[norareidy]

S:

Suggested change

	The following example queries the collection to return the top three
	longest books.
	- The query matches all documents because the query filter is empty.
	- The descending ``sort()`` method on the ``length`` field returns longer books before shorter books.
	- The ``limit()`` method specifies returning only the first ``3`` results.
	This example performs the following actions:
	- Uses an empty query filter to match all documents in the collection
	- Calls the ``sort()`` method to apply a descending sort on the ``length`` field to the results
	- Calls the ``limit()`` method to return only the first ``3`` results

[norareidy]

S: emphasize limit instead of sort

Suggested change

	:emphasize-lines: 4
	:emphasize-lines: 5

[norareidy]

Okay I actually think the Sort section should come first (before both skip and limit) since it's used in both of them, should've clarified that last time oops

[norareidy]

S: "preceding" + missing space

Suggested change

	above case,the documents that have ``title`` values of ``"A Dance with Dragons"`` and
	preceding example, the documents that have ``title`` values of ``"A Dance with Dragons"`` and

[norareidy]

S:

Suggested change

	Use the ``skip()`` method to omit documents from the beginning of the list of
	returned documents for a read operation. You can combine ``skip()`` with
	Use the ``skip()`` method to omit documents from the beginning of the read operation results. You can combine ``skip()`` with

[norareidy]

S:

Suggested change

	The following example queries the collection for the books with the second and third
	highest lengths.
	- The query matches all documents because the query filter is empty.
	- The descending ``sort()`` method on the ``length`` field returns longer books before shorter books.
	- The ``skip()`` method specifies that the first matching document is omitted from the result.
	This example queries the collection for the books with the second and third
	highest lengths by performing the following actions:
	- Uses an empty query filter to match all documents in the collection
	- Calls the ``sort()`` method to apply a descending sort to the ``length`` field, which returns longer books before shorter books
	- Calls the ``skip()`` method to omit the first matching document from the result

[norareidy]

S: I don't think you need to emphasize any lines here

[norareidy]

S:

Suggested change

	document and specifies returning only the first result:
	document and including only the first result:

[norareidy]

S: since you're talking about the options here, not the methods, you can remove the ()

Suggested change

	You can combine the ``limit()``, ``sort()``, and ``skip()`` options in a single
	You can combine the ``limit``, ``sort``, and ``skip`` options in a single

[baileympearson]

I'm not sure the best place to mention this or honestly if it is even worth mentioning - but if you use the chaining API you must specify all options before starting to iterate the cursor.

const cursor = find();
await cursor.next();
cursor.limit(5); // does not work

Should we mention this limitation of the builder API somewhere?

[shuangela]

I think this is good information for users to have, thanks for informing me! I added a note about it in the overview section, let me know if the wording is technically correct! Do you know where the API documentation about this would be/if there is any? I was looking in https://mongodb.github.io/node-mongodb-native/6.15/ but couldn't find anything specifically about the chaining API.

[baileympearson]

We don't document this, although it might be nice to add to our doc comments. I looked at the code though and we actually throw an error in this scenario. For example, here's the source code for limit:

/**
   * Set the limit for the cursor.
   *
   * @param value - The limit for the cursor query.
   */
  limit(value: number): this {
    this.throwIfInitialized();  // <-- here we throw
    if (this.findOptions.tailable) {
      throw new MongoTailableCursorError('Tailable cursor does not support limit');
    }

    if (typeof value !== 'number') {
      throw new MongoInvalidArgumentError('Operation "limit" requires an integer');
    }

    this.findOptions.limit = value;
    return this;
  }

So I guess, anybody who tries to set these values after the cursor is initialized would see errors. Given that, do you think its worth documenting explicitly here as well? We could also just add a note to the API docs that specify that they will throw if the cursor is initialized.

Also, its worth mentioning that this applies to all our cursor chaining APIs, not just skip/limit/sort. So if we document it, it would be nice to document this behavior more generally than just for these three options, I think? This error is thrown for any option that affects the actual cursor command the driver sends (ex: project, allowDiskUse, comment, etc).

[shuangela]

I think we can still leave this note in these docs for now, and based on our discussion in slack about standardization, we also made another ticket about adding a note about this cursor chaining behavior.