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.

[limzykenneth]

@GregStanton There are no major work on the documentation currently with @nickmcintyre probably already done with most if not all of the copy edits. That being said, if you would like to jump straight to JSDoc, might you consider making this a proposal for the 2.0 RFC at #6678?

[nickmcintyre]

@limzykenneth actually, I have about half of the reference left to edit. For example, I haven't edited the references for the Shape functions @GregStanton mentioned.

@GregStanton this issue seems very helpful and focused. How about we discuss the proposed policies in this issue for now? One full example in both YUIDoc and JSDoc syntax would be helpful.

[GregStanton]

Thanks @limzykenneth for the quick response. Also, about the 2.0 RFC: amazing, exciting work! Thank you so much for putting that together and for tagging me. I jotted down a bunch of general questions and ideas as I read over it. I'll post those over in #6678 so I can get a better feel for the RFC, and then I'll be able to respond more thoughtfully to your question about the current issue on default values.

@nickmcintyre Thanks for the update! Yeah, a concrete example with syntax from each is a great idea. I can try to put one together after I respond about the RFC.

[ar-rana]

@GregStanton if there's room for more volenteers, I would love to work on this issue!

[dz016]

Hi @GregStanton! Being new to contributing to p5.js and open source in general, I'm keen on getting involved in this specific issue. I believe it will be a valuable opportunity for me to gain a deeper understanding of the contribution process.

[GregStanton]

Good news! I think the YUIDoc and JSDoc syntax for default parameter values is actually the same. See the YUIDoc documentation and the JSDoc documentation. The @default tag I originally cited has a different purpose. This should simplify some things. I'll follow up soon with more details on our next steps.

[davepagurek]

Great find @GregStanton!

[Ravi3727]

Could you let me know if this issue has been solved? If not then can I contribute to it?

[GregStanton]

Hi @Ravi3727! Thanks for your interest! Work on this issue has not started yet. Once I know a little more, I'll ping you and the other volunteers with instructions on how to get started. (Some of the work could be done now, but I'm hoping to get some feedback on a related proposal soon. Then I'll know which branch we need to work on.)

[Viking-Pradeep]

I want to work on this issue. Can you please elaborate more on this?

[dev3z]

hey @GregStanton I am interested in working on this issue.

[GregStanton]

Thanks for adding this to the list of proposals for p5.js 2.0, @limzykenneth!

I realized that YUIDoc and JSDoc actually have the same syntax for default parameters (see this comment), and I've updated the body of this issue to reflect this. So, I think work is ready to start on this issue, but two questions remain before I can reply to the volunteers.

1. Do you think this proposal has enough support for it to be accepted for p5.js 2.0, so that work may begin now? Or do we want to iron out the acceptance process first? Since 2.0 proposals will tend to affect many features, conflicts are more likely than usual. So, I suppose it may be helpful to know all the proposals that are being accepted before beginning work on any of them, to reduce conflicts. Then again, if we postpone work now, we're definitely slowing down the process in order to avoid hypothetical problems in the future. It seems like a judgement call.
2. Once work begins, would it make sense to resolve this issue first (on the dev 2.0 branch), and after that, make any changes needed to convert to JSDoc syntax? This may make sense since a lot of volunteers have already offered to work on this issue, and doing the work in stages may reduce conflicts (this issue is intended to be beginner friendly). But I don't know if there will be other proposals related to the inline documentation.

[vaishnavi192]

@GregStanton hey I am a new contributor in processing. Ping me as well whenever work on this issue get started. Also, as a new contributor I wanted to ask how can I find easier issues to get started with?

[Jeroenvh99]

@GregStanton I really like this idea to improve the documentation and I'd like to help working on this, what part can I work on?

[GregStanton]

Hi all! Thanks so much to everyone for offering to help with this issue. Right now, I'm hoping to hear back about the implementation process for p5.js 2.0. There are other proposals related to this one (for now, you can see the list of current proposals at the top of issue #6678 and in the original Request for Comments). So we may need to organize the work in stages. I appreciate your patience! I'll ping everyone who has volunteered for this issue once we're ready to start the work, assuming this proposal is accepted.

Also, @vaishnavi192, we've started to apply the "Good First Issue" label to more issues, but there may still be some suitable issues that haven't received that label yet. When choosing an issue to work on, the main thing to keep in mind is that two areas of work are currently being prioritized: (1) bug fixes and (2) p5.js 2.0.

For p5.js 2.0, new proposals are still welcome, and we have a new issue form specifically for that purpose. So the best way to get involved with that effort is to submit a proposal of your own, provide feedback on an existing proposal, or offer to help implement an existing proposal (as you did here).

[rupalchandak]

@GregStanton Hey I really like the idea and want to contribute in this ....

[vaishnavi192]

@GregStanton Thanks for the great explanation!! I would love to contribute to this! I'll check how submitting proposal works. For now I would love to contribute in feedback and volunteer. Thanks a lot

[msudipta888]

i want to solve this issue

[iamniky]

I'm interested in implementing the policies. I expect to be able to help with at least a group of functions, if not more.

[GregStanton]

@jules-kris: When I was working on a new name for beginShape()'s default kind, I came up with a quick list of naming criteria. It was helpful to score different options we were considering against each criterion ("Excellent", "Good", "Okay", "Weak", or "Bad"). I thought I'd include the list here, in case it helps with the implementation of this issue more generally. Feedback on these criteria is welcome :)

1. Descriptiveness
   • Unambiguous
   • Accurate
   • Avoids abbreviations
2. Consistency
   • Is free of conflicts within the p5 API
   • Is free of conflicts with other APIs (mainly the Canvas and SVG APIs)
   • Is free of conflicts in related contexts (art, math, ...)
   • Follows casing conventions
3. Simplicity
   • Familiar to beginners
   • Easy to spell
   • Concise
4. Future proof (will likely continue to satisfy the other criteria if context changes)

Notes:

1. It may not always be possible to satisfy all the criteria with "Excellent" scores, but a score of "Okay" or lower might indicate room for improvement.
2. Perhaps we can include this list in the contributor docs as well, for general naming? We could maybe add a "searchable" criterion (i.e. is easy to find in searches), and conventions like an "is" prefix for Booleans.