Merge pull request #809 from processing/new-20-docs

Update 2.0 documentation

Author: ksen0

Diff for: public/reference/data.json

@@ -306,4 +306,4 @@ p5.prototype.myMethod = function(){
 
 **Examples are great, too!** They show people what your library can do. Because this is all JavaScript, people can see them running online before they download anything.[ ](http://jsfiddle.net/) You can create a collection of examples on the p5.js web editor to showcase how your library works.
 
-**Submit your library!** Once your library is ready for distribution and you’d like it included on the [p5js.org/libraries](https://p5js.org/libraries/) page, please submit a pull request on the p5.js website GitHub repository following [this instruction](https://github.com/processing/p5.js-website/blob/main/docs/contributing_libraries.md)!
+**Submit your library!** Once your library is ready for distribution and you’d like it included on the [p5js.org/libraries](https://p5js.org/libraries/) page, please submit a pull request on the p5.js website GitHub repository following [this intruction](https://github.com/processing/p5.js-website/blob/main/docs/contributing_libraries.md)!

Diff for: public/search-indices/en.json

@@ -0,0 +1,162 @@
+---
+title: |
+  JSDoc Best Practices
+description: >
+  Documentation on the website is built from the comments in the p5.js repo.
+  Here are a few things to keep in mind in order for the documentation to be
+  parsed correctly!
+---
+
+
+Documentation on the website is built from the comments in the p5.js repo. Here are a few things to keep in mind in order for the documentation to be parsed correctly!
+
+## For everything
+
+* At the top of a file, add a comment with the `@module` tag, and optionally also the `@submodule`. These reference the category and subcategory names that the contents of the file should appear under in the reference:
+
+  e.g. for just a category:
+
+  ```js
+  /**
+   * @module Rendering
+   */
+  ```
+
+  e.g. for both:
+
+  ```js
+  /**
+   * @module Data
+   * @submodule LocalStorage
+   */
+  ```
+
+## For classes
+
+* Create classes *outside* of the addon function, and assign them to `p5` *inside.* The class name should be the same always:
+
+  ```js
+  class MyClass {
+    // ...
+  }
+
+  export default function myAddon(p5, fn) {
+     p5.MyClass = MyClass;
+  }
+  ```
+
+* Document class methods directly above the members in classes, *without* a `@method` tag:
+
+  ```js
+  class MyClass {
+    /**
+     * Description goes here
+     */
+    myMethod() {
+      return 4;
+    }
+  }
+  ```
+
+* Documentation for the class itself should go at the spot where the class is added to `p5` and not right next to the class definition. This needs to include the `@class` tag, including a `p5.` prefix on the class name. Also include the parameters for the constructor in this description, if they exist.
+
+  ```js
+  class MyClass {
+    constructor(n) {
+      this.n = n;
+    }
+  }
+
+  export default function myAddon(p5, fn) {
+    /**
+     * Description of the class goes here!
+     *
+     * @class p5.MyClass
+     * @param {Number} n A number to pass in
+     */
+     p5.MyClass = MyClass;
+  }
+  ```
+
+* Documentation for class properties should appear after the class is added to `p5`, not within the class itself. It needs to have the `@for` tag referencing its class, and the `@property` tag naming the property itself:
+
+  ```js
+  class MyClass {
+    myProperty;
+    constructor() {
+      myProperty = 2;
+    }
+  }
+
+  export default function myAddon(p5, fn) {
+    /**
+     * Description of the class goes here!
+     *
+     * @class p5.MyClass
+     */
+     p5.MyClass = MyClass;
+
+     /**
+      * Description of the property goes here!
+      *
+      * @property {Number} myProperty
+      * @for p5.MyClass
+      */
+  }
+  ```
+
+## For global functions
+
+* Add a comment with the `@method` tag listing its name:
+
+  ```js
+  export default function myAddon(p5, fn) {
+    /**
+     * Description goes here!
+     *
+     * @method myFunction
+     */
+    p5.myFunction = function() {
+      return 8;
+    };
+  }
+  ```
+
+* For dynamically generated methods, do the same as usual, but add `@for p5`.
+
+  ```js
+  function myAddon(p5, fn) {
+    for (const key of ['nameA', 'nameB']) {
+      fn[key] = function() {
+        return `Hello from ${key}!`;
+      };
+    }
+
+    /**
+     * @method nameA
+     * @for p5
+     */
+
+    /**
+     * @method nameB
+     * @for p5
+     */
+  }
+  ```
+
+* Mark things that you don't want showing up as `@private`. This is done automatically for methods whose names start with `_`.
+
+  ```js
+  class MyClass {
+    /**
+     * @private
+     */
+    privateMethodA() {
+      // ...
+    }
+
+    _privateMethodB() {
+      // ...
+    }
+  }
+  ```

Diff for: public/search-indices/es.json

@@ -2,54 +2,14 @@
 title: getLevel
 module: p5.sound
 submodule: p5.sound
-file: lib/addons/p5.sound.js
-description: |
-  <p>Returns a single Amplitude reading at the moment it is called.
-  For continuous readings, run in the draw loop.</p>
-line: 3209
+file: src/Amplitude.js
+description: Get the current amplitude value of a sound.
+line: 63
 isConstructor: false
 itemtype: method
-example:
-  - |-
-
-    <div><code>
-    function preload(){
-      sound = loadSound('/assets/beat.mp3');
-    }
-
-    function setup() {
-      let cnv = createCanvas(100, 100);
-      cnv.mouseClicked(toggleSound);
-      amplitude = new p5.Amplitude();
-    }
-
-    function draw() {
-      background(220, 150);
-      textAlign(CENTER);
-      text('tap to play', width/2, 20);
-
-      let level = amplitude.getLevel();
-      let size = map(level, 0, 1, 0, 200);
-      ellipse(width/2, height/2, size, size);
-    }
-
-    function toggleSound(){
-      if (sound.isPlaying()) {
-        sound.stop();
-      } else {
-        sound.play();
-      }
-    }
-    </code></div>
 class: p5.Amplitude
-params:
-  - name: channel
-    description: |
-      <p>Optionally return only channel 0 (left) or 1 (right)</p>
-    type: Number
-    optional: true
 return:
-  description: Amplitude as a number between 0.0 and 1.0
+  description: Amplitude level (volume) of a sound.
   type: Number
 chainable: false
 ---

Diff for: public/search-indices/hi.json

@@ -2,63 +2,16 @@
 title: setInput
 module: p5.sound
 submodule: p5.sound
-file: lib/addons/p5.sound.js
-description: |
-  <p>Connects to the p5sound instance (main output) by default.
-  Optionally, you can pass in a specific source (i.e. a soundfile).</p>
-line: 3117
+file: src/Amplitude.js
+description: Connect an audio source to the amplitude object.
+line: 53
 isConstructor: false
 itemtype: method
-example:
-  - |-
-
-    <div><code>
-    function preload(){
-      sound1 = loadSound('/assets/beat.mp3');
-      sound2 = loadSound('/assets/drum.mp3');
-    }
-    function setup(){
-      cnv = createCanvas(100, 100);
-      cnv.mouseClicked(toggleSound);
-
-      amplitude = new p5.Amplitude();
-      amplitude.setInput(sound2);
-    }
-
-    function draw() {
-      background(220);
-      text('tap to play', 20, 20);
-
-      let level = amplitude.getLevel();
-      let size = map(level, 0, 1, 0, 200);
-      ellipse(width/2, height/2, size, size);
-    }
-
-    function toggleSound(){
-      if (sound1.isPlaying() && sound2.isPlaying()) {
-        sound1.stop();
-        sound2.stop();
-      } else {
-        sound1.play();
-        sound2.play();
-      }
-    }
-    </code></div>
 class: p5.Amplitude
 params:
-  - name: snd
-    description: |
-      <p>set the sound source
-                                           (optional, defaults to
-                                           main output)</p>
-    type: SoundObject|undefined
-    optional: true
-  - name: smoothing
-    description: |
-      <p>a range between 0.0 and 1.0
-                                            to smooth amplitude readings</p>
-    type: Number|undefined
-    optional: true
+  - name: input
+    description: '- An object that has audio output.'
+    type: Object
 chainable: false
 ---
 

Diff for: public/search-indices/ko.json

@@ -2,18 +2,17 @@
 title: smooth
 module: p5.sound
 submodule: p5.sound
-file: lib/addons/p5.sound.js
-description: |
-  <p>Smooth Amplitude analysis by averaging with the last analysis
-  frame. Off by default.</p>
-line: 3293
+file: src/Amplitude.js
+description: Get the current amplitude value of a sound.
+line: 73
 isConstructor: false
 itemtype: method
 class: p5.Amplitude
 params:
-  - name: set
-    description: |
-      <p>smoothing from 0.0 <= 1</p>
+  - name: Smooth
+    description: >-
+      Amplitude analysis by averaging with the last analysis frame. Off by
+      default.
     type: Number
 chainable: false
 ---

Diff for: public/search-indices/zh-Hans.json

@@ -2,23 +2,16 @@
 title: amp
 module: p5.sound
 submodule: p5.sound
-file: lib/addons/p5.sound.js
-description: |
-  <p>Set amplitude (volume) of a mic input between 0 and 1.0. <br/></p>
-line: 6257
+file: src/AudioIn.js
+description: Set amplitude (volume) of a mic input between 0 and 1.0.
+line: 81
 isConstructor: false
 itemtype: method
 class: p5.AudioIn
 params:
-  - name: vol
-    description: |
-      <p>between 0 and 1.0</p>
+  - name: amplitudeAmount
+    description: An amplitude value between 0 and 1.
     type: Number
-  - name: time
-    description: |
-      <p>ramp time (optional)</p>
-    type: Number
-    optional: true
 chainable: false
 ---