Add better documentation for bindgen. #5025

gagik · 2022-10-20T10:56:57Z

What, How & Why?

Adds better documentation for methods and fields of Realm instance classes. I came up with some principles that decisions were made when I was not sure how to organize, prioritising consistency with legacy documentation as well as clear formatting from language server when viewed from VSCode.

General prioritisation order of comments: @params > @throws > @returns > @example > @since.
All tags start with uppercase i.e. @returns The sum. The only exception is if it is referring to boolean / other references that happen to lowercase, i.e. @returns true if...
No tags are followed by a dash (this was in legacy docs and is actually ignored by JSDoc but for sake of consistency this is removed).
No tags other than @throws should specify types since this is TypeScript.
@throws is followed by Error type (i.e. {Error}) then either If or When.
@returns is followed by The / A if applicable. If it returns a boolean it follows the format: @returns true if X, false if not.
@since is kept since it would be easier to remove it then add it back.
I tried to replace links with italicised bold text i.e. {@link Realm.Bold bold} => ***bold***. This is because the links in i.e. VSCode were not useful and just led to the source code when clicked which did not seem appropriate in this context. In my opinion best developer experience would be for the links to link to the documentation website for the specific function. I did not see italicised bold text used before, so adding this specific styling to some words will hopefully make it easier to go through them and consider re-adding links in the future. I do think there are other instances where a link to doc would be useful so this is not exhaustive.
All methods that override built-in JS parent class methods (i.e. forEach, map) have not been commented as they already have built-in documentation that is inherited.

Let me know if any of these "rules" seem unreasonable and I could change it, they are mostly following the old docs.

☑️ ToDos

📝 Changelog entry
📝 Compatibility label is updated or copied from previous entry
📝 Update COMPATIBILITY.md
🚦 Tests
🔀 Executed flexible sync tests locally if modifying flexible sync
📦 Updated internal package version in consuming package.jsons (if updating internal packages)
📱 Check the React Native/other sample apps work if necessary
📝 Public documentation PR created or is not necessary
💥 Breaking label has been applied or is not necessary

If this PR adds or changes public API's:

typescript definitions file is updated
jsdoc files updated
Chrome debug API is updated if API is available on React Native

kraenhansen · 2022-10-20T11:01:01Z

packages/realm/src/Realm.ts

-   * @param  {string} path
-   * @param  {any} encryptionKey?
-   * @returns number
+   * @param path - The path to the file where the


Not at a computer now, but I'm curious if the dash after param name is ignored? If not, it should probably go away.

The dash does get ignored but It could be good to make this consistent anyways.

Okay since old docs have the dash in most places, I will try to make sure params have dashes

kraenhansen · 2022-10-20T11:05:25Z

packages/realm/src/Realm.ts

+   * Searches for a Realm object by its primary key.
+   * @param type - The type of Realm object to search for.
+   * @param primaryKey - The primary key value of the object to search for.
+   * @throws If type passed into this method is invalid or if the object type did


I'm wondering if it make sense to pick an order of these annotations? So @return is always before @throw and perhaps we could add an eslint plugin for that? Just lower the possible variations among these comments.

The way old docs were made, return was always after the throw, so I kept it this way, generally I kept this order:
param > throws > return > since

kraenhansen · 2022-10-20T11:06:10Z

packages/realm/src/Realm.ts

+   * @param type - The type of Realm object to search for.
+   * @param primaryKey - The primary key value of the object to search for.
+   * @throws If type passed into this method is invalid or if the object type did
+   *   not have a `primaryKey` specified in its {@link ObjectSchema}.


Does this link resolve correctly?

links seem to work weirdly... they don't really link to meaningful places (they do link to code) so I saw thinking of removing them.

gagik · 2022-10-20T14:43:46Z

packages/realm/src/App.ts

+ * This describes the options used to create a Realm.App instance.
+ * @property id - The id of the Atlas App Services application.
+ * @property baseUrl - The base URL of the Atlas App Services server.
+ * @property timeout - General timeout (in millisecs) for requests. TODO


Not sure if these fields are going to be added in the future.

Most likely.

packages/realm/src/Collection.ts

packages/realm/src/Dictionary.ts

packages/realm/src/List.ts

gagik · 2022-10-20T14:50:58Z

packages/realm/src/Realm.ts

+   * Searches for a Realm object by its primary key.
+   * @param type - The type of Realm object to search for.
+   * @param primaryKey - The primary key value of the object to search for.
+   * @throws If type passed into this method is invalid or if the object type did


The way old docs were made, return was always after the throw, so I kept it this way, generally I kept this order:
param > throws > return > since

packages/realm/src/Realm.ts

gagik · 2022-10-21T08:09:47Z

There are still some changes to be made but seems like good time to discuss things.

gagik · 2022-10-21T13:36:41Z

packages/realm/src/App.ts

+ * This describes the options used to create a Realm.App instance.
+ * @prop id - The id of the Atlas App Services application.
+ * @prop baseUrl - The base URL of the Atlas App Services server.
+ * @prop timeout - General timeout (in millisecs) for requests. TODOC


Are these fields meant to be added in the future? Should I keep them?

packages/realm/src/Dictionary.ts

packages/realm/DOCUMENTATION.md

kraenhansen · 2022-11-03T10:07:45Z

@gagik if you find a moment, it would be awesome to get this rebased and merged 🤞

packages/realm/src/OrderedCollection.ts

Co-authored-by: Kræn Hansen <[email protected]>

* Add documentation for Realm * More documentation and changes. * Remove more links and add docs. * More format consistency. * Add documentation doc. * Minor corrections * Remove discuss * Minor improvements * Update packages/realm/src/OrderedCollection.ts Co-authored-by: Kræn Hansen <[email protected]> Co-authored-by: Kræn Hansen <[email protected]>

cla-bot bot added the cla: yes label Oct 20, 2022

kraenhansen reviewed Oct 20, 2022

View reviewed changes

gagik commented Oct 20, 2022

View reviewed changes

gagik marked this pull request as ready for review October 21, 2022 08:09

gagik requested a review from kraenhansen October 21, 2022 08:09

gagik force-pushed the gagik/betterdocs branch from d375758 to 39b66f8 Compare October 21, 2022 12:51

gagik commented Oct 21, 2022

View reviewed changes

gagik force-pushed the gagik/betterdocs branch from debecd7 to 0855399 Compare October 21, 2022 13:41

gagik commented Oct 21, 2022

View reviewed changes

packages/realm/DOCUMENTATION.md Show resolved Hide resolved

kraenhansen force-pushed the bindgen branch 3 times, most recently from 962dd1a to 4de03e3 Compare October 26, 2022 09:23

gagik added 6 commits November 3, 2022 11:54

Add documentation for Realm

cc6de43

More documentation and changes.

2db27ec

Remove more links and add docs.

3e23a81

More format consistency.

c8040ba

Add documentation doc.

81ca66b

Minor corrections

91158ff

gagik force-pushed the gagik/betterdocs branch from f3778d5 to 91158ff Compare November 3, 2022 11:53

gagik added 2 commits November 3, 2022 12:58

Remove discuss

33d0422

Minor improvements

fea08f5

kraenhansen reviewed Nov 7, 2022

View reviewed changes

packages/realm/src/OrderedCollection.ts Outdated Show resolved Hide resolved

Update packages/realm/src/OrderedCollection.ts

691b434

Co-authored-by: Kræn Hansen <[email protected]>

kraenhansen merged commit 756e34e into bindgen Nov 9, 2022

kraenhansen deleted the gagik/betterdocs branch November 9, 2022 06:23

github-actions bot locked as resolved and limited conversation to collaborators Mar 15, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add better documentation for bindgen. #5025

Add better documentation for bindgen. #5025

gagik commented Oct 20, 2022 •

edited

Loading

kraenhansen Oct 20, 2022

gagik Oct 20, 2022

gagik Oct 20, 2022

kraenhansen Oct 20, 2022

gagik Oct 20, 2022

kraenhansen Oct 20, 2022

gagik Oct 20, 2022

gagik Oct 20, 2022

kraenhansen Oct 24, 2022

gagik Oct 20, 2022

gagik commented Oct 21, 2022

gagik Oct 21, 2022

kraenhansen commented Nov 3, 2022

Add better documentation for bindgen. #5025

Add better documentation for bindgen. #5025

Conversation

gagik commented Oct 20, 2022 • edited Loading

What, How & Why?

☑️ ToDos

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gagik commented Oct 21, 2022

Choose a reason for hiding this comment

kraenhansen commented Nov 3, 2022

gagik commented Oct 20, 2022 •

edited

Loading