Docs simple edits #5482

Zearin · 2021-11-27T18:25:50Z

Changes:

This is a follow-up to my original efforts in Pull Request #5447. The main differences in this request are:

I tried to break up my edits into per-file commits
For any commits that went beyond simple formatting, I tried to summarize those edits in each commit
I tried to keep all my edits simpler to make review easier
I only worked my way through part of the reference docs (up through 📁dom/), to (hopefully) make it easier to review

If this works out, I’ll continue this line of work through the next chunk of reference docs and send another Pull Request.

PR Checklist

Inline documentation is included / updated

Also: * Use `—` instead of spaced hyphen-minus * Fix minor capitalization

* Remove superflous `<br>` * Fixed some missing spaces after commas and periods * Use the serial (“Oxford”) comma

Also: * Fixed unnecessarily capitalized “The”

* Include parentheses when referencing functions * Fix capitalization * Add paragraph break to `id()` * Add link to `dragLeave()`

Also: * Use escaped entities in HTML for comparison operators * Fix plural form in `for` loop * Add missing space after several periods

* Add missing parentheses for functions * Add missing period at end of sentence for `noCanvas()` * Spaced the list items in `blendMod()` (since this is an unusually long block of HTML in the docstring) * Add serial (“Oxford”) comma in description of `mode` param of `blendMode()`

* Add serial (“Oxford”) comma where appropriate * Add paragraph break in description for `arc()` * Add paragraph break in description for `line()` * Remove superfluous comma after “The way these parameters are interpreted”

* Lots of commas (especially for `strokeCap()`, where their absence made reading the description difficult)

* Follow “Note” with a colon, not a comma * Fix mislabelled parameter in the description for `curveTightness()`

* Add serial (“Oxford”) comma

* Add paragraph breaks in `pop()` and `push()` * Minor edit to end of `p5()` docstring

Linkify references to functions.

* Add links to references to Dictionary classes * Fix capitalization of params * Fix param descriptions using the param name itself as part of the description

Also: * Used `#exampleIdSelector, .exampleClassSelector` in descriptions * Add parentheses to referenced functions/methods * Fix some capitalization * Fix (some) param descriptions using the param name itself as part of the description * Add `<` and `>` around HTML tags to aid visual grepping HTML * Minor edits to param descriptions for input elements * Use punctuation to help the reader correctly parse the description of the `type` param for `createCapture()` * Add some paragraph breaks descriptions (usually between opening summary and subsequent descriptions of optional params * Change “current time” to `currentTime` to make it explicit that p5.js is using the `currentTime` DOM property

welcome · 2021-11-27T18:25:51Z

🎉 Thanks for opening this pull request! Please check out our contributing guidelines if you haven't already. And be sure to add yourself to the list of contributors on the readme page!

Zearin · 2021-11-27T18:28:51Z

@outofambit: Is this better than the last PR? It’s still a decent chunk of diffs—but I tried to keep the edits much simpler this time, and I only did a portion of the reference docs.

Zearin · 2021-12-04T16:53:35Z

@Qianqianye: The docs list you as the other person in charge of the Reference docs. If @outofambit is busy, would you consider taking a look?

limzykenneth · 2022-01-20T15:48:44Z

src/dom/dom.js

- * @param  {Number|Constant} w    width of the element, either AUTO, or a number
- * @param  {Number|Constant} [h] height of the element, either AUTO, or a number
+ * @param  {Number|Constant} w    width of the element, either a number, or `AUTO`
+ * @param  {Number|Constant} [h] height of the element, either a number, or `AUTO`


This line and the line above cannot be changed because its structure is used to infer types in the documentation generation process. See more here.

limzykenneth · 2022-01-20T15:58:02Z

src/core/p5.Renderer.js

@@ -10,7 +10,7 @@ import * as constants from '../core/constants';
 /**
 * Main graphics and rendering context, as well as the base API
 * implementation for p5.js "core". To be used as the superclass for
- * Renderer2D and Renderer3D classes, respectively.
+ * `Renderer2D` and `Renderer3D` classes, respectively.


Renderer3D should be RendererGL instead

limzykenneth · 2022-01-20T16:01:15Z

src/core/reference.js

@@ -113,8 +113,8 @@
 */

 /**
- * The greater than operator <a href="#/p5/>">></a>
- * evaluates to true if the left value is greater than
+ * The greater than operator <a href="#/p5/>">&gt;</a>


The link doesn't work as the > in the URL should be encoded in this case.

Same for those below

limzykenneth · 2022-01-20T16:15:23Z

src/dom/dom.js

+ * Searches the page for the first element that matches the given CSS selector string (can be an `#id`, a `.class`,
+ * a tag name, or a combination) and returns it as a <a href="#/p5.Element">p5.Element</a>.
+ * The DOM node itself can be accessed with `.elt`.
+ * Returns `null` if none found. You can also specify a `container` to search within.


I'm not sure "container" here needs to be enclosed in code tags as it's not referencing a very specific item in this case.

Same for below.

limzykenneth · 2022-01-20T16:18:18Z

src/dom/dom.js

@@ -451,13 +451,13 @@ p5.prototype.createA = function(href, html, target) {

 /**
 * Creates a slider `&lt;input&gt;&lt;/input&gt;` element in the DOM.
- * Use .size() to set the display length of the slider.
+ * Use .`size()` to set the display length of the slider.


The dot before size() probably should be enclosed in backticks as well.

Same as below.

limzykenneth · 2022-01-20T16:22:08Z

src/dom/dom.js

- * @param  {Function} callback callback function for when a file is loaded
- * @param  {Boolean} [multiple] optional, to allow multiple files to be selected
+ * @param  {Function} callback Callback function to run when a file is loaded
+ * @param  {Boolean} [multiple] (optional) Allow multiple files to be selected


"(optional)" is not required here as it is added automatically when the parameter is marked as so.

limzykenneth · 2022-01-20T16:25:41Z

src/dom/dom.js

 *
 * @method hasClass
- * @returns {boolean} a boolean value if element has specified class
- * @param c {String} class name of class to check
+ * @param {String} c The `class` name to check


"class" don't need to be enclosed in code tag here, or the next one in the param tag below needs to be enclosed.

Qianqianye · 2022-07-07T04:40:57Z

Thanks @Zearin for making the edits and @limzykenneth for making the suggestions. @Zearin, will you be able to make some new edits based on @limzykenneth's suggestion? Thank you!

Zearin added 19 commits November 21, 2021 13:40

docs: Formatting (📁accessibility)

b5462f6

Also: * Use `—` instead of spaced hyphen-minus * Fix minor capitalization

docs: Formatting (📁color)

ef28b51

* Remove superflous `<br>` * Fixed some missing spaces after commas and periods * Use the serial (“Oxford”) comma

docs: Formatting (📁core/constants.js)

61dd1d8

docs: Formatting (📁core/environment.js)

508b971

Also: * Fixed unnecessarily capitalized “The”

docs: Formatting (📁core/main.js)

87326f5

docs: Formatting (📁core/p5.Element.js)

a1e6f72

* Include parentheses when referencing functions * Fix capitalization * Add paragraph break to `id()` * Add link to `dragLeave()`

docs: Formatting (📁core/p5.Renderer.js)

21597b3

docs: Formatting (📁core/p5.Renderer2D.js)

0494e43

docs: Formatting (📁core/reference.js)

8f1ea00

Also: * Use escaped entities in HTML for comparison operators * Fix plural form in `for` loop * Add missing space after several periods

docs: Formatting (📁core/shape/2d_primitives.js)

b855cf6

* Add serial (“Oxford”) comma where appropriate * Add paragraph break in description for `arc()` * Add paragraph break in description for `line()` * Remove superfluous comma after “The way these parameters are interpreted”

docs: Formatting (📁core/shape/attributes.js)

f7ca6a1

* Lots of commas (especially for `strokeCap()`, where their absence made reading the description difficult)

docs: Formatting (📁core/shape/curves.js)

53f0090

* Follow “Note” with a colon, not a comma * Fix mislabelled parameter in the description for `curveTightness()`

docs: Formatting (📁core/shape/vertex.js)

555161c

* Add serial (“Oxford”) comma

docs: Formatting (📁core/structure.js)

426a065

* Add paragraph breaks in `pop()` and `push()` * Minor edit to end of `p5()` docstring

docs: Formatting (📁core/transform.js)

57da039

docs: Formatting (📁core/transform.js)

9390a12

Linkify references to functions.

docs: Formatting (📁data/p5.TypedDict.js)

44017fe

* Add links to references to Dictionary classes * Fix capitalization of params * Fix param descriptions using the param name itself as part of the description

Zearin mentioned this pull request Dec 11, 2021

docs: Fix typos (its/it’s) #5500

Merged

2 tasks

limzykenneth requested changes Jan 20, 2022

View reviewed changes

limzykenneth reviewed Jan 20, 2022

View reviewed changes

Zearin closed this Oct 8, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs simple edits #5482

Docs simple edits #5482

Zearin commented Nov 27, 2021

welcome bot commented Nov 27, 2021

Zearin commented Nov 27, 2021

Zearin commented Dec 4, 2021

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

limzykenneth Jan 20, 2022

Qianqianye commented Jul 7, 2022

Docs simple edits #5482

Docs simple edits #5482

Conversation

Zearin commented Nov 27, 2021

PR Checklist

welcome bot commented Nov 27, 2021

Zearin commented Nov 27, 2021

Zearin commented Dec 4, 2021

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

Qianqianye commented Jul 7, 2022