Increase consistency in usage and documentation of default values

[GregStanton]

Increasing Access

By improving consistency and making information easier to find, this change will increase access to beginners, as well as to users and contributors with limited free time.

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build Process
• Unit Testing
• Internalization
• Friendly Errors
• Other (specify if possible)

Problem: Using and documenting default values

It's not easy to maintain consistency and completeness when many contributors regularly add new cool stuff! So it's not unexpected that there are inconsistencies in the p5.js API and missing descriptions in the p5.js reference. After describing the problem in more detail, I'll propose a standardization to help us solve it. I'm not sure if any of these issues will be addressed by recent work on the documentation or the upcoming p5.js website, but the usage issues would remain either way.

Using defaults

The naming of default values is inconsistent: many default values are named, but some are not. Here are two examples of unnamed default values:

1. The beginShape() function has an optional kind parameter. Its default value has a meaningful interpretation, but it has no name. This prevents us from giving beginContour() a kind parameter, as we plan to do for #6560. ¹
2. As another example, debugMode() has three possible modes, but only two of them are named: GRID and AXES. Based on the description of the mode parameter, users may think these are the only two modes, and they may ask "Which is the default?" The answer: neither of them.

Documenting defaults

Determining default values from the reference is more difficult than necessary. Even when default values are identified, they're identified in inconsistent places, sometimes with inaccurate descriptions. Consider the examples from above:

1. In the reference page for beginShape(), the default value is referred to only implicitly, and it isn't identified at all in the parameter description. The reference refers to the same parameter as both "kind" and "mode," so it's not always clear what's being described. It also describes the default shapes as polygons; however, the actual default shapes don't need to be closed and their segments don't need to be straight.
2. In the reference page for debugMode(), the default mode is described in different levels of detail throughout the body of the function description, which spans multiple paragraphs. The default mode isn't specified in the parameter description, and it's never named. (Seeing the effect of the default setting also requires the user to interact with each example in a specific way that's not entirely specified in the verbal description.)

Additional examples

We've seen two examples so far: beginShape() and debugMode(). However, there are other mode functions: angleMode(), colorMode(), ellipseMode(), rectMode(), blendMode(),imageMode(), and textureMode(). Fortunately, all these other mode functions already have named defaults, but none of their reference pages identify those defaults in the parameter descriptions. These are just some examples. There may be other functions separate from these with optional parameters whose default values aren't named or identified.

Solution

Explicitly identifying default values in a consistent location—and giving them descriptive names—will make them easier to find and understand. After all, it'll be easier to write clear descriptions once we have clear names. To help us implement these changes, I propose two policies and three stages of work.

Policies

1. Always provide a descriptive name for default values of string (or symbol) parameters. (In the case of beginShape(), SEGMENTS is a reasonable name. In the case of debugMode(), GRID_AND_AXES is a reasonable name.)
2. Always identify default values by name in the parameter descriptions, using the [parameterName = defaultName] syntax.

Edit: In the original post, the @default syntax was mistakenly cited above.

Stages of work

To implement these policies, we can go through the p5.js reference and make some simple changes. I propose we do the work in three stages:

• Add the proposed policies to the p5.js contributor docs.
• Go through the reference pages for all functions/methods, and introduce names for any unnamed default values.
• Go through the reference pages for all functions/methods, and identify default values in parameter descriptions.

To limit the scope of this issue, I'm not proposing we change the language in the descriptions of the functions themselves (i.e. the descriptions at the top of their reference pages). As part of #6560, I'm planning to create a separate issue with proposed language for at least some of the functions under the Shape section of the p5.js reference: beginContour(), beginShape(), bezierVertex(), curveVertex(), endContour(), endShape(), quadraticVertex(), vertex(), and normal(). I've already updated the descriptions for some of these.

How you can help!

The p5.js reference contains quite a few functions, but we can easily divide up the work according to sections in the p5.js reference, since it's already so well organized. If we reach a consensus about making these changes, I can open up separate issues for each stage; that will help us to discuss any new names before we introduce them to the public API, for example.

Here's what you can do to start:

1. Share your opinion on the proposed policies! It'd be good to reach a consensus on them before making any changes.
2. Comment on this issue to indicate that you're interested in implementing the policies, and indicate how many functions you expect to have time to update (a single function, a group of functions in the p5.js reference, or all functions).

Footnotes

1. We want contours to use the containing shape's kind when called with no arguments. So, if the containing shape has a non-default kind like POINTS, beginContour() won't be able to go back to the default kind without naming it. ↩

[Hemant2A2]

@GregStanton this seems to be a good idea! I'm interested in working on this issue.

[GregStanton]

That's great @Hemant2A2! Thanks for commenting. I'll @ mention you on this issue if it becomes clear that we're going to move forward on this.

[Artimus100]

@GregStanton Great idea!! would love to work on it!

[Vishal2002]

Can I also work on this issue?

[GregStanton]

Thanks to @Hemant2A2, @Artimus100, @Vishal2002, and any other volunteers who want to help! Any changes made for this issue should be straightforward and non-breaking, but I want to make sure there's a wide consensus since this proposal affects the contributor docs, many reference pages, and multiple functions.

Also, as this issue is largely about consistency, we can make an inventory of pending changes before we merge anything, in order to verify that the names for default values will be consistent. Once the changes are ready, we can merge them to the vertex-refactor branch (I'm linking this issue to #6560, since some of these changes are needed to resolve that issue, and I'm hoping to prevent confusion by making all changes for that issue on one branch).

I'll @ mention everyone who volunteers on this issue about next steps once we get feedback from the project leadership and stewards. Note that in the mentions below, I'm removing duplicates in cases where one person serves in multiple roles.

Pinging active maintainers who are familiar with #6560:
@limzykenneth
@davepagurek

Pinging other stewards (contributor docs):
@asukaminato0721, @SoundaryaKoutharapu, @richardegil, @hannahvy, @bayomayo

Pinging other stewards (accessibility):
@calebfoss, @cosmicbhejafry, @apoorva-a98, @tedkmburu, @Zarkv, @SkylerW99, @itsjoopark, @nhasalajoshi

Thanks again everyone!

[RohitPaul0007]

I would love to work on the issue @GregStanton

[davepagurek]

@limzykenneth I was looking through https://jsdoc.app/tags-param and noticed that jsdoc has a syntax for describing default parameters. Could that be a way of showing default values after we switch away from yuidoc?

[limzykenneth]

For parameters definitely, for things like default modes though it can be more ambiguous and probably won't have a specific syntax that deals with state machine's default state.

[GregStanton]

Thanks @davepagurek and @limzykenneth!

My main question is whether this work would conflict with any other work on the p5.js documentation that I don't know about. If you both think the proposal makes sense, I can start moving this forward (we have enough volunteers). Just let me know if there's anyone else who needs to take a look first.

Also, thanks for looking into the JSDoc syntax. Now that you mention it, a benefit of the YUIDoc syntax is that it should be easy to search for @default and replace it with JSDoc syntax later on.

[sudhanshuv1]

I also want to work on this! I can update some functions in the p5.js reference.