[WIP] Docs: Add initial draft of Strands documentation (feedback wanted) #7940
Conversation
|
Hi @perminder-17 Could you please review this new PR? It replaces the previous one #7920 due to merge conflicts and now targets Thank you! |
There was a problem hiding this comment.
Hi @Abhayaj247, thank you for your work! I noticed you added a new p5.strands.js file under src/webgl just for documentation, but it isn’t referenced anywhere else in the repo. Could you instead place your docs to the end of shaderGenerator.js? That way we avoid adding an unused file and keep things cleaner.
Hi @perminder-17, I’ve moved the p5.strands JSDoc documentation to the end of shaderGenerator.js as requested, starting from line 1644. The separate file has been removed. Could you please confirm if the style, detail, and placement look good? Once you approve, I’ll proceed to document the remaining hooks in the same format. Please let me know if you’d like any further adjustments. Thank you! |
src/webgl/ShaderGenerator.js
Outdated
| * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. | ||
| * | ||
| * This hook is available in: | ||
| * - {@link p5.baseMaterialShader} |
There was a problem hiding this comment.
I think although this is valid JSDoc, we don't yet support it in p5's jsdoc-to-reference pipeline. Currently we use <a href="...">, e.g.:
Line 1207 in 0da0430
There was a problem hiding this comment.
Hi @davepagurek ,
I've updated all references to use the <a href="..."> syntax that p5.js supports, following the pattern from p5.Font.js. All links now use the format <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.
src/webgl/ShaderGenerator.js
Outdated
|
|
||
| /* ------------------------------------------------------------- */ | ||
| /** | ||
| * @typedef {Object} Vertex |
There was a problem hiding this comment.
I'm also not sure that typedef docs will show up in the reference, even though this does simplify the writing of the function parameter. If you test your branch on the p5.js-website repo, what does this look like? If it doesn't render, we may need to either document this object inline, or update the website to be able to support this syntax.
There was a problem hiding this comment.
@davepagurek Thank you for the guidance on the @typedef issue. I've removed it and documented the vertex object properties inline in the parameter description to ensure clarity and compatibility with the documentation pipeline.
src/webgl/ShaderGenerator.js
Outdated
| * @param {function(ColorComponents): { color: {r: number, g: number, b: number}, opacity: number }} callback | ||
| * A callback function which receives a ColorComponents struct and returns the final color and opacity. | ||
| * | ||
| * @see {@link p5.baseMaterialShader} |
There was a problem hiding this comment.
Similar to above, we probably don't support @see yet, but feel free to use regular links in a paragraph explaining why you might want to check out these related references!
There was a problem hiding this comment.
@davepagurek , I've removed all @see tags since they're not supported in the current documentation pipeline. The documentation now relies on clear descriptions and contextual examples to guide users to related references.
src/webgl/ShaderGenerator.js
Outdated
| * myShader = baseMaterialShader().modify(() => { | ||
| * combineColors(components => { | ||
| * // Custom color combination: add a red tint | ||
| * let color = { |
There was a problem hiding this comment.
Although you can access .r, .g, .b, and .a properties, the return value would need to be either [r, g, b, a] as an array, or more explicitly, vec4(r, g, b, a) -- we don't yet support an object notation for this. (Also it will need to be just the one object, and not an object with separate color and opacity properties, for it to compile correctly I think.)
There was a problem hiding this comment.
This also makes me wonder what the best way to document the inputs object is, since it's not exactly any normal type. @lukeplowden do you have any thoughts on this? We could call it a vec4 and then explain in the description of the function what this means, or even not give it a type at all, and just have an explanation in the description.
There was a problem hiding this comment.
Although you can access
.r,.g,.b, and.aproperties, the return value would need to be either[r, g, b, a]as an array, or more explicitly,vec4(r, g, b, a)-- we don't yet support an object notation for this. (Also it will need to be just the one object, and not an object with separate color and opacity properties, for it to compile correctly I think.)
@davepagurek , I've corrected the combineColors example to return vec4(r, g, b, a) instead of object notation. The example now properly demonstrates the correct return format that will compile successfully.
This also makes me wonder what the best way to document the
inputsobject is, since it's not exactly any normal type. @lukeplowden do you have any thoughts on this? We could call it avec4and then explain in the description of the function what this means, or even not give it a type at all, and just have an explanation in the description.
Excellent point about the input object documentation. I've updated the parameter descriptions to clearly specify the available properties without using complex type annotations. For getWorldInputs, I've documented the vertex object properties inline, and for combineColors, I've listed all available color component properties in the description.
|
Thank you for the comprehensive feedback @davepagurek . I've addressed all the documentation compatibility issues:
The documentation should now be fully compatible with the current p5.js documentation pipeline. If there are any other modifications or improvements you’d like to see, please let me know—I'm happy to make further adjustments as needed. |
Note: This PR replaces #7920 to resolve merge conflicts that occurred while rebasing onto the
dev-2.0branch.This PR introduces new JSDoc reference entries for several
p5.strandshooks, as discussed in #7919 and based on recent feedback.Key updates:
getWorldInputscombineColorsgetPointSizesrc/webgl/p5.strands.jsfor clarity and modularity.Request for feedback:
Once I receive feedback and confirmation on the format and placement, I’ll proceed to document the remaining hooks in the same style.
Thank you for your time and guidance!