Update docs to add description about versioning and writing documentation

Author: leeyi45

docs/src/modules/2-bundle/4-conventions/1-basic.md

@@ -29,7 +29,7 @@ Neither default nor rest parameters are currently supported due to an [issue](ht
 
 ## 2. Cadet facing functions should not use array destructuring for parameters
 
-Javascript allows us to pass destruct iterables directly within the function declaration:
+Javascript allows us to destruct iterables directly within a function's parameters:
 
 ```ts
 export function foo([x, y]: [string, string]) {
@@ -124,7 +124,22 @@ Lists are actually introduced in Source 1, which would make the above function c
 functionality specific to arrays, then consider using Source Lists instead.
 :::
 
-## 4. Making use of `js-slang/stdlib`
+## 4. Semantic Versioning
+
+[Semantic Versioning](https://semver.org) refers to a convention on how version numbers should be specified. In your bundle's `package.json`, a `version` field should
+be specified:
+
+```jsonc {3}
+{
+  "name": "@sourceacademy/bundle-bundle0",
+  "version": "1.0.0"
+}
+```
+
+This version number should follow the rules of semantic versioning. `js-slang` will use this version number to determine if it currently has the latest version of your bundle
+compatible with its current version.
+
+## 5. Making use of `js-slang/stdlib`
 
 Bundles, where necessary, should use the implementations of libraries such as `list` or `stream` from the `js-slang` standard library:
 

docs/src/modules/2-bundle/5-documentation/5-documentation.md

@@ -11,7 +11,11 @@ By reading comments and type annotations, `typedoc` is able to generate both hum
 
 ## Writing Documentation
 
-`typedoc` reads both Typescript type annotations, as well as [TSDOC](https://tsdoc.org) style comments. It will build documentation for all functions and constants exported by the particular module.
+`typedoc` reads both Typescript type annotations, as well as [TSDOC](https://tsdoc.org) style comments. It will build documentation for all functions and constants exported by the particular bundle's entry point.
+For example, since the `curve` bundle exports the `make_point` function, `typedoc` will generate documentation for it. However, there are many other functions that the bundle does not expose that won't have documentation generated.
+
+Documentation should be written in [Markdown](https://www.markdownguide.org/getting-started/). That way, both IntelliSense and Typedoc will be able to process it. During documentation generation,
+the markdown is converted to raw HTML.
 
 ::: details Type Aware annotations
 [JSDoc](https://jsdoc.app) (and TSDoc) both support annotations that express type information directly like `@type` or annotations that can optionally contain type information like `@param` and `@returns`.
@@ -23,7 +27,9 @@ so as not to confuse Typedoc and ensure that the Typescript compiler is able to
 If you do need to the type of an export to be documented differently from its type in Typescript source code, you can use a [type map](../7-type_map).
 :::
 
-Let us look at an example from the `curve` module.
+Let us look at more examples from the `curve` module.
+
+### Functions
 
 ```ts
 // functions.ts
@@ -43,66 +49,21 @@ export function make_point(x: number, y: number): Point {
 }
 ```
 
-```ts
-// index.ts
-export { make_point } from './functions.ts';
-```
-
-Since the `curve` bundle exports the `make_point` function, `typedoc` will generate documentation for it.
-
-Documentation should be written in [Markdown](https://www.markdownguide.org/getting-started/). That way, both IntelliSense and Typedoc will be able to process it. During documentation generation,
-the markdown is converted to raw HTML.
-
-The following sections are conventions for writing documentation.
-
-### Entry Point
-
-At the entry point for each bundle, there should be a block comment that provides general information about the bundle.
-
-This example is taken from the `repeat` bundle:
+Notice that in the example above, each `@param` tag is followed directly by the name of the parameter its describing, which is then followed
+by the description of the parameter itself.
 
+Missing the documentation for a parameter is okay (not that you should), but trying to document a parameter that doesn't exist will cause a linting
+error:
 ```ts
-// repeat/src/index.ts
 /**
- * Test bundle for Source Academy modules repository
- * @author Loh Xian Ze, Bryan
- * @author Tang Xin Kye, Marcus
- * @module repeat
+ * Oops p1 isn't documented!
+ * @param p3 This parameter doesn't exist and so this will cause a lint error!
  */
-
-export { repeat, twice, thrice } from './functions';
-```
-
-It is important that you provide an `@module` tag in this description. Otherwise, the build tools may not be able to detect your bundle's
-documentation properly.
-
-> [!TIP]
-> An ESLint Rule has been configured specifically for this purpose, so a lint error should appear if you forget to do so.
-
-### Use of `@hidden`
-
-If there are exports you want hidden from the output of the documentation, you must use the `@hidden` tag.
-
-The example below is taken from the `rune` bundle:
-
-```ts
-// rune/src/type_map.ts
-import createTypeMap from '@sourceacademy/modules-lib/type_map';
-
-const typeMapCreator = createTypeMap();
-
-export const { functionDeclaration, variableDeclaration, classDeclaration } = typeMapCreator;
-
-/** @hidden */
-export const type_map = typeMapCreator.type_map;
+export function foo(p1: string, p2: string) {
+  // ...implementation
+}
 ```
 
-This causes `type_map` to be removed from the documentation, even if it is exported from `rune/src/index.ts`.
-
-> [!WARNING]
-> Bundle `type_map`s are supposed to be internal implementation details hidden from users. If you forget to apply a `@hidden` tag to
-> your bundle's type map export, the build tools will show a warning.
-
 ### Use of `@function`
 
 Following v0.28, Typedoc only documents function-like types as functions if they are explicitly typed as functions (see the issue [here](https://github.com/TypeStrong/typedoc/issues/2881)).
@@ -168,6 +129,67 @@ The export will now be correctly recognized as a function:
 
 There is no automatic way to make this distinction, so it is up to the bundle authors to make sure that this convention is adhered to.
 
+### Variables/Constants
+
+Constants can be documented in a similar fashion:
+```ts
+/**
+ * Represents the mathematical constant PI
+ */
+const PI: number = 3.14159;
+```
+
+Also similar to function return types and parameters, because the types of variables is determined by the Typescript compiler, it is unnecessary
+to use the `@type` tag here.
+
+### Entry Point
+
+At the entry point for each bundle, there should be a block comment that provides general information about the bundle.
+
+This example is taken from the `repeat` bundle:
+
+```ts
+// repeat/src/index.ts
+/**
+ * Test bundle for Source Academy modules repository
+ * @author Loh Xian Ze, Bryan
+ * @author Tang Xin Kye, Marcus
+ * @module repeat
+ */
+
+export { repeat, twice, thrice } from './functions';
+```
+
+It is important that you provide an `@module` tag in this description. Otherwise, the build tools may not be able to detect your bundle's
+documentation properly.
+
+> [!TIP]
+> An ESLint Rule has been configured specifically for this purpose, so a lint error should appear if you forget to do so.
+
+### Use of `@hidden`
+
+If there are exports you want hidden from the output of the documentation, you must use the `@hidden` tag.
+
+The example below is taken from the `rune` bundle:
+
+```ts
+// rune/src/type_map.ts
+import createTypeMap from '@sourceacademy/modules-lib/type_map';
+
+const typeMapCreator = createTypeMap();
+
+export const { functionDeclaration, variableDeclaration, classDeclaration } = typeMapCreator;
+
+/** @hidden */
+export const type_map = typeMapCreator.type_map;
+```
+
+This causes `type_map` to be removed from the documentation, even if it is exported from `rune/src/index.ts`.
+
+> [!WARNING]
+> Bundle `type_map`s are supposed to be internal implementation details hidden from users. If you forget to apply a `@hidden` tag to
+> your bundle's type map export, the build tools will show a warning.
+
 ### Other Tags
 
 There are a variety of tags that Typedoc supports. This list can be found [here](https://typedoc.org/documents/Tags.html). When writing your documentation you should use these tags

docs/src/modules/3-tabs/3-editing.md

@@ -58,7 +58,7 @@ You can also add the dependency directly by modifying your `package.json`:
 
 ```jsonc {4}
 {
-  "name": "@sourceacademy/bundle-bundle0",
+  "name": "@sourceacademy/tab-Tab0",
   "dependencies": {
     "lodash": "^4.0.0"
   }

src/bundles/binary_tree/src/__tests__/index.test.ts

@@ -1,6 +1,6 @@
+import { list } from 'js-slang/dist/stdlib/list';
 import { describe, expect, it } from 'vitest';
 import * as funcs from '../functions';
-import { list } from 'js-slang/dist/stdlib/list';
 
 describe(funcs.is_tree, () => {
   it('returns false when argument is not a tree', () => {