Performance info in documentation

[jonahsnider]

Motivation

Writing performant Discord.js bots is important for many users, but the reference documentation is missing information about performance.

For example this snippet has O(n) time complexity:

role.members.has(userId);

While this one has O(1) time complexity:

member.roles.has(roleId);

This is only clear to users if they view the source and learn that role.members is a getter with O(n) time complexity.

This is not good, users shouldn't be expected to review the source before deciding to use a feature of the library.

Possible solutions

Aside from simply rewriting the library in Rust (🚀), the next best solution is including information about performance in either every API item or in API items where it's important.

An API item is something like a property, method, or class. The term comes from Microsoft's TSDoc spec.

To test out different solutions I recommend using discordjs/collection since it's not very large and has a wide range of computational complexities across all the methods.

Here are a few ideas I came up with for accomplishing this:

Adding @performance doc tags

Include @performance doc tags where relevant.

diff --git a/src/structures/Role.js b/src/structures/Role.js
index f0ee3a86..7628bb7f 100644
--- a/src/structures/Role.js
+++ b/src/structures/Role.js
@@ -194,6 +194,7 @@ class Role extends Base {
    * The cached guild members that have this role
    * @type {Collection<Snowflake, GuildMember>}
    * @readonly
+   * @performance O(n)
    */
   get members() {
     return this.guild.members.cache.filter(m => m.roles.cache.has(this.id));

This doc tag denotes that the getter has O(n) time and space complexity in the worst case.

The specific syntax of the @performance tag could use improvement and to aid in automated parsing.

The downside of calculating those values by hand is that it requires a maintainer to recursively go through the implementation of each API item.
This also introduces lots of overhead as changing the computational complexity of any API item requires updating the @performance tag of everything downstream which consumes it.
Perhaps a tool could be written to construct a graph representing API items and their "dependencies" (other API items) and then use it to calculate the computational complexity of each API item.

Best practices for performance

In addition to documenting the performance of API items, adding a page to the documentation which includes short snippets (like the one in the motivation section) provides a simple way for users to see best practices for performance without delving into the full reference documentation.