Skip to content

Commit 11e9322

Browse files
nbogienbogie
committed
inline ref guide: minor tidies and typos
* Remove @ from all section nav ids and links. ...to avoid overkeen link rewriting in build:contrib-docs * Push section later on linking references. Common. * Simplify headings: e.g. "Documenting functions"
1 parent 54cd278 commit 11e9322

1 file changed

Lines changed: 108 additions & 100 deletions

File tree

‎contributor_docs/contributing_to_the_p5js_reference.md‎

Lines changed: 108 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,11 @@
88

99
## Table of Contents
1010
* [A quick introduction to reference comments](#a-quick-introduction-to-reference-comments)
11-
* [Reference comment blocks for functions](#reference-comment-blocks-for-functions)
12-
* [Reference comment blocks for p5.js variables](#reference-comment-blocks-for-p5js-variables)
11+
* [Documenting functions](#documenting-functions)
12+
* [Documenting p5.js variables](#documenting-p5js-variables)
1313
* [Adding examples](#adding-examples)
1414
* [Using assets in examples and descriptions](#using-assets)
15+
* [Linking to other p5.js features](#linking)
1516
* [Less common JSDoc tags](#less-common-jsdoc-tags)
1617
* [Generating and previewing the reference](#generating-and-previewing-the-reference)
1718
* [Linting the comments to find errors](#linting-the-docs)
@@ -63,7 +64,7 @@ Anything in a block in this manner will be interpreted as reference documentatio
6364

6465
In this style of reference comments, each comment block is further divided into individual elements, which we will have a look at next.
6566

66-
## Reference comment blocks for functions
67+
## Documenting functions
6768

6869
In abstract, a comment block for a p5 _function_ typically looks as follows. (We've included the tags that will mark each section but the correct syntax will be shown shortly).
6970

@@ -175,7 +176,7 @@ If you like, you can find the source code for this `sin` function in the p5 repo
175176

176177
Now we'll look at each section in turn.
177178

178-
### <a id="@description"></a>Describing the function
179+
### <a id="description"></a>Describing the function
179180

180181
Example:
181182

@@ -208,9 +209,8 @@ In some places, you may see the `@description` tag used. It explicitly marks t
208209
209210
#### The first sentence of the description
210211
211-
The first sentence in the description, in particular, should concisely summarize what the function does. It will almost always be necessary to omit detail here.
212-
213-
This first sentence will sometimes be presented alone with the function name (e.g. in [the function list](https://beta.p5js.org/reference/#Shape) on the front page of the reference website, where it can help the reader understand quickly if the function is what they're looking for.
212+
The first sentence in the description, in particular, should concisely summarize what the function does.
213+
It may be presented alone with the function name in listings (e.g. in [the function list](https://beta.p5js.org/reference/#Shape) on the front page of the reference website), where it should help the reader understand quickly if the function is what they're looking for.
214214
215215
**Examples of first sentences of function descriptions**
216216
@@ -253,67 +253,6 @@ Multiplies a vector by a scalar and returns a new vector.
253253
254254
```
255255
256-
#### <a id="linking"></a>Linking to another p5.js feature
257-
258-
A hyperlink HTML element (with the `a` tag) can be used within a description to link to the documentation of another relevant feature of the p5.js library.
259-
260-
Example:
261-
262-
```
263-
<a href="#/p5/circle">circle()</a>
264-
```
265-
266-
Note that the URL should _not_ include a direct link to the website.
267-
268-
With the [exception of constants](#linking-to-constants), the URL should be of the following "fragment" or "hash" form:
269-
270-
`#/class/property`
271-
272-
Example URLs linking to functions and variables:
273-
274-
* `#/p5/circle`
275-
* `#/p5/createCanvas`
276-
* `#/p5/fill`
277-
* `#/p5/mouseX`
278-
* `#/p5.Vector/lerp`
279-
* `#/p5.Vector/dist`
280-
* `#/p5.Image/width`
281-
282-
Examples URLS linking to classes:
283-
284-
* `#/p5.Color`
285-
* `#/p5.Image`
286-
* `#/p5.Vector`
287-
288-
As seen above, when there's no property involved, just a class itself, the second slash is generally omitted.
289-
290-
Full examples:
291-
292-
From the description of [dist](https://beta.p5js.org/reference/p5/dist/) in [calculation.js](https://github.com/processing/p5.js/blob/dev-2.0/src/math/calculation.js)
293-
```
294-
* Use <a href="#/p5.Vector/dist">p5.Vector.dist()</a>
295-
* to calculate the distance between two
296-
* <a href="#/p5.Vector">p5.Vector</a> objects.
297-
```
298-
299-
From the description of [pmouseX](https://beta.p5js.org/reference/p5/pmousex/):
300-
```
301-
* Its value is <a href="#/p5/mouseX">mouseX</a>
302-
* from the previous frame.
303-
```
304-
305-
<a id="linking-to-constants"></a>**Exception: Linking to constants**
306-
307-
Links to constants should instead follow this form:
308-
309-
`#/p5/constants/name-of-constant`
310-
311-
Example URLS:
312-
313-
* `#/p5/constants/DEGREES`
314-
* `#/p5/constants/CENTER`
315-
* `#/p5/constants/LEFT`
316-
317256
#### Using images within the description section
318257
319258
In some cases it may be desirable to include, in the description, images or audio or video to help explain or demonstrate a function's working.
@@ -336,15 +275,15 @@ Here's a cut-down example from the source of [`applyMatrix`](https://github.com/
336275
* ...
337276
```
338277
339-
### <a id="@method"></a>`@method` - specifying the function name
278+
### <a id="method"></a>`@method` - specifying the function name
340279
341280
[`@method`](https://jsdoc.app/tags-function) is used to define the name of the function, in this case `sin`. Note that the function name does not include the brackets `()`.
342281
343282
You may sometimes see this missing from the reference. In that case JSDoc will try to infer it by looking at the name of the function from the following source code. It is recommended to include the function name using the @method tag where possible.
344283
345284
This tag is also useful when detailing multiple signatures for a function (see later).
346285
347-
### <a id="@param"></a>`@param` - specifying details of each parameter
286+
### <a id="param"></a>`@param` - specifying details of each parameter
348287
349288
[`@param`](https://jsdoc.app/tags-param) is used to define the parameters or arguments that the function accepts. It is used once per parameter.
350289
@@ -451,7 +390,7 @@ Here's some of the documentation for `loadImage`, which has an optional paramete
451390

452391
#### Links in param descriptions
453392

454-
You can include links in the description of a parameter. See [linking](#linking).
393+
You can include links in the description of a parameter. For how to link to another reference page see [linking](#linking), later.
455394

456395
Example:
457396
```
@@ -460,7 +399,7 @@ Example:
460399
* the current <a href="#/p5/angleMode">angleMode()</a>.
461400
```
462401

463-
### <a id="@return"></a>`@return` - specifying the return value
402+
### <a id="return"></a>`@return` - specifying the return value
464403

465404
[`@return`](https://jsdoc.app/tags-returns) is used to define the return value of the function.
466405

@@ -482,7 +421,7 @@ If the function does not return a value, the `@return` tag can be left out.
482421

483422
If the function returns a value but you want it to be type `any`, use `{*}`, e.g. `@return {*} description here...`
484423

485-
You can include links in the description of a return. See [linking](#linking).
424+
You can include links in the description of a return. For how to link to another reference page see [linking](#linking), later.
486425

487426
More examples of `@return`:
488427

@@ -646,7 +585,7 @@ In this rare situation, it is possible to use a last-resort mechanism to inject
646585

647586
Bear in mind this is a last resort. Try to correctly specify the types in the documentation comments wherever possible.
648587

649-
## Reference comment blocks for p5.js variables
588+
## Documenting p5.js variables
650589

651590
So far, we have looked at how to write references for functions. Variables follow the same structure but use different tags.
652591

@@ -679,7 +618,7 @@ Example: the reference comment block for the built-in variable, `mouseX`:
679618

680619
The start of the block contains the description of the variable (`mouseX` in this case). The same rules apply from function descriptions: Use a clear short first line, you can use markdown and HTML and assets in the description.
681620

682-
### <a id="@property"></a>The `@property` tag
621+
### <a id="property"></a>The `@property` tag
683622

684623
To define the name of the variable, we use [`@property`](https://jsdoc.app/tags-property) instead of `@method`. `@property` follows the same syntax as `@param` for defining the type and its name.
685624

@@ -704,7 +643,7 @@ From [`src/image/p5.Image.js`](https://github.com/processing/p5.js/blob/dev-2.0/
704643
* @property {Number[]} pixels
705644
```
706645

707-
### <a id="@readonly"></a>The `@readonly` tag
646+
### <a id="readonly"></a>The `@readonly` tag
708647

709648
The `@readonly` tag is present on most p5.js variables and is used internally to indicate this value should not be overwritten directly by a library user.
710649

@@ -864,11 +803,80 @@ Finally, for every example you add, you are required to use the p5.js function `
864803

865804
For more on `describe()` visit the [web accessibility contributor documentation](./web_accessibility/#describe), and the [Writing Accessible Canvas Descriptions](https://beta.p5js.org/tutorials/writing-accessible-canvas-descriptions/) tutorial.
866805

806+
807+
## <a id="linking"></a>Linking to other p5.js features
808+
809+
A hyperlink can be used within a description or `@param` or `@return` to link to the reference documentation of another relevant p5.js feature.
810+
811+
Example:
812+
813+
```
814+
<a href="#/p5/circle">circle()</a>
815+
```
816+
817+
Note that the URL should _not_ include a direct link to the website.
818+
819+
With the [exception of constants](#linking-to-constants), the URL should be of the following "fragment" or "hash" form:
820+
821+
`#/class/property`
822+
823+
Example URLs linking to functions and variables:
824+
825+
* `#/p5/circle`
826+
* `#/p5/createCanvas`
827+
* `#/p5/fill`
828+
* `#/p5/mouseX`
829+
* `#/p5.Vector/lerp`
830+
* `#/p5.Vector/dist`
831+
* `#/p5.Image/width`
832+
833+
Example URLs linking to classes:
834+
835+
* `#/p5.Color`
836+
* `#/p5.Image`
837+
* `#/p5.Vector`
838+
839+
As seen above, when there's no property involved, just a class itself, the second slash is generally omitted.
840+
841+
Full examples:
842+
843+
From the description of [dist](https://beta.p5js.org/reference/p5/dist/) in [calculation.js](https://github.com/processing/p5.js/blob/dev-2.0/src/math/calculation.js)
844+
```
845+
* Use <a href="#/p5.Vector/dist">p5.Vector.dist()</a>
846+
* to calculate the distance between two
847+
* <a href="#/p5.Vector">p5.Vector</a> objects.
848+
```
849+
850+
From the description of [pmouseX](https://beta.p5js.org/reference/p5/pmousex/):
851+
```
852+
* Its value is <a href="#/p5/mouseX">mouseX</a>
853+
* from the previous frame.
854+
```
855+
856+
From the `@return` statement of [createVector()](https://beta.p5js.org/reference/p5/createVector/):
857+
```
858+
* @return {p5.Vector} new
859+
* <a href="#/p5.Vector">p5.Vector</a> object.
860+
```
861+
862+
863+
<a id="linking-to-constants"></a>**Exception: Linking to constants**
864+
865+
Links to constants should instead follow this form:
866+
867+
`#/p5/constants/name-of-constant`
868+
869+
Example URLS:
870+
871+
* `#/p5/constants/DEGREES`
872+
* `#/p5/constants/CENTER`
873+
* `#/p5/constants/LEFT`
874+
867875
## Less common JSDoc tags
868876

869877
With all the above you should have most of the tools needed to write and edit p5.js reference comments. However, there are a few more specialized usages of JSDoc reference comments that you may come across in p5.js. These are situationally useful and not something that you need often.
870878

871-
### <a id="@private"></a>`@private` tag
879+
### <a id="private"></a>`@private` tag
872880

873881
You can use the `@private` if a property or variable or class is private. If a feature is marked as `@private` it will not be included as part of the rendered reference on the website. This is done automatically for methods whose names start with `_`.
874882

@@ -892,7 +900,7 @@ invert(canvas) {
892900

893901
### `@module` and related tags
894902

895-
#### <a id="@module"></a>`@module` and `@submodule`
903+
#### <a id="module"></a>`@module` and `@submodule`
896904

897905
At the top of each source code file will be a comment block with a `@module` tag. A module is a top-level grouping of features in the reference pages on the website. This does _not_ necessarily correspond to any specific software `module` concept in the code itself.
898906

@@ -929,7 +937,7 @@ For both:
929937
*/
930938
```
931939

932-
#### <a id="@for"></a>The `@for` tag
940+
#### <a id="for"></a>The `@for` tag
933941

934942
The `@for` tag defines the relationship between this module and the overall `p5` class, effectively saying this module is a part of the `p5` class.
935943

@@ -961,7 +969,7 @@ Example of `@for` and `@requires`
961969
* @requires constants
962970
*/
963971
```
964-
#### <a id="@beta"></a>The @beta tag - marking experimental API features
972+
#### <a id="beta"></a>The @beta tag - marking experimental API features
965973

966974
This tag is used to mark that a feature is experimental and that its details may change or it may be removed. A warning will be presented explaining this on the reference page.
967975

@@ -983,7 +991,7 @@ It should be placed on a separate line in the comment block and does not need an
983991
*/
984992
```
985993

986-
#### <a id="@deprecated"></a>The @deprecated tag
994+
#### <a id="deprecated"></a>The @deprecated tag
987995

988996
Marks that a feature will be removed from a future version of p5.js, possibly also indicating a better option.
989997

@@ -1274,25 +1282,25 @@ getRow (r) {
12741282
12751283
Click on any tag to go to its section in the text.
12761284
1277-
| Tag | Usage | Notes |
1278-
|-------------------------------|----------------------------------|----------------------------------------------------|
1279-
| [@method](#@method) | @method name | Omitted in certain cases. |
1280-
| [@description](#@description) | @description text here | If omitted, uses first text before _any_ tag. |
1281-
| [@param](#@param) | @param \{type\} name Description | Name must match the function parameter. |
1282-
| [@return](#@return) | @return \{type\} Description | Omit type if it returns undefined. |
1283-
| [@example](#adding-examples) | @example Code on next lines... | Each gets `@example` before and a newline after. |
1284-
| [\`\`\`js example](#inserted-examples) | \`\`\`js example | Insert early examples _within_ the description. |
1285-
| [@chainable](#@chainable) | @chainable | Instead of `@return`, if it returns same object. |
1286-
| [@property](#@property) | @property \{type\} name | Most p5 variables are properties of p5 class. |
1287-
| [@readonly](#@readonly) | @readonly | Mark that a property is not writeable by the user. |
1288-
| [@static](#@static) | @static | Static method or property of a class. |
1289-
| [@for](#@for) | @for className | Associate a feature with a class. |
1290-
| [@module](#@module) | @module | Groups features for display. |
1291-
| [@submodule](#@module) | @submodule | Groups features for display. |
1292-
| [@class](#@class) | @class | Marks a class. |
1293-
| [@beta](#@beta) | @beta | Mark an experimental feature. |
1294-
| [@deprecated](#@deprecated) | @deprecated | A deprecated feature is intended to be removed. |
1295-
| [@private](#@private) | @private | Internal details not for publishing. |
1285+
| Tag | Usage | Notes |
1286+
|------------------------------|----------------------------------|----------------------------------------------------|
1287+
| [@method](#method) | @method name | Omitted in certain cases. |
1288+
| [@description](#description) | @description text here | If omitted, uses first text before _any_ tag. |
1289+
| [@param](#param) | @param \{type\} name Description | Name must match the function parameter. |
1290+
| [@return](#return) | @return \{type\} Description | Omit type if it returns undefined. |
1291+
| [@example](#adding-examples) | @example Code on next lines... | Each gets `@example` before and a newline after. |
1292+
| [\`\`\`js example](#inserted-examples) | \`\`\`js example | Insert early examples _within_ the description. |
1293+
| [@chainable](#chaining) | @chainable | Instead of `@return`, if it returns same object. |
1294+
| [@property](#property) | @property \{type\} name | Most p5 variables are properties of p5 class. |
1295+
| [@readonly](#readonly) | @readonly | Mark that a property is not writeable by the user. |
1296+
| [@static](#static) | @static | Static method or property of a class. |
1297+
| [@for](#for) | @for className | Associate a feature with a class. |
1298+
| [@module](#module) | @module | Groups features for display. |
1299+
| [@submodule](#module) | @submodule | Groups features for display. |
1300+
| [@class](#class) | @class | Marks a class. |
1301+
| [@beta](#beta) | @beta | Mark an experimental feature. |
1302+
| [@deprecated](#deprecated) | @deprecated | A deprecated feature is intended to be removed. |
1303+
| [@private](#private) | @private | Internal details not for publishing. |
12961304
12971305
12981306
## <a id="doc-differences-v1-to-v2"></a>Appendix: Summary of documentation differences between p5.js v1 and v2

0 commit comments

Comments
 (0)