Contributing to standard library documentation

traveler_hauptman

I'm finally have a few spare moments to start experimenting with featurescript. I'm in that brief stage of everything is new, and I am having lots of questions pop up, which once I get up to speed will be obvious and forgotten details.

An example is, 'How do I set the origin of a sketch?', which, after digging through the std library is 'It's inherited from the plane it is created on.' A breadcrumb in the documentation for newSketch() would have saved me some time stabbing in the dark trying to figure it out.

I would happily add a line or two of documentation here and there if there were a way to do that. If not directly usable, it would show you what concepts are not obvious for someone coming in fresh. Are you able to push/pull between documents if I create a copy of the std lib?

ilya_baran

Hi Traveler,

Glad you have time to start experimenting -- your feedback on what is not obvious is very welcome.

In terms of the specific mechanism of contributing (documentation or code) to std, we still need to figure it out -- there are copyright issues, attribution, the technical mechanism, and our own processes for review, QA, etc. to consider.  Technically, we can't easily push/pull between documents -- the most convenient way at this point is probably for you to just point out where you'd like additional info (in a forum post -- your example in newSketch is a good one) and we'll add it.

In this case, we will also point to newSketchOnPlane, which can be used for full control over the sketch coordinate system (whereas newSketch orients the plane canonically and sets the origin to be the projection of the world origin onto the plane).

traveler_hauptman

/**
 * Create a new sketch as a feature. Orients the plane canonically and sets the 
 * sketch origin to be the projection of the world origin onto the plane.
 */
annotation { "Feature Type Name" : "Sketch", "UIHint" : "CONTROL_VISIBILITY" }
export function newSketch(context is Context, id is Id, value is map) returns Sketch

and

/**
 * Create a new sketch for internal use within a feature. Sets the sketch origin 
 * to be the origin of the plane.
 * @param value {{ @field sketchPlane }}
 */
export function newSketchOnPlane(context is Context, id is Id, value is map) returns Sketch

ilya_baran

Slightly reworded versions will make their way into the next update in a few weeks.

traveler_hauptman

I'm just going to keep adding to this thread....

/**
 * Extrudes one or more edges or faces in a given direction with one or two end conditions.
+ * The direction vector for the startBound is the negative of 'direction', hence the startDepth
+ * must be premultiplied by -1.
 * @param id : @autocomplete `id + "extrude1"`
 * @param definition {{
 *      @field entities {Query} : Edges and faces to extrude.
 *      @field direction {Vector} : The 3d direction in which to extrude.
 *              @eg `evPlane(context, {"face" : entities}).normal` to extrude perpendicular to the first planar entity
 *      @field endBound {BoundingType} : The type of bound at the end of the extrusion. Cannot be `SYMMETRIC`.
 *              @eg `BoundingType.BLIND`
 *      @field endDepth {ValueWithUnits} : @requiredif {`endBound` is `BLIND`.}
 *              How far from the `entities` to extrude.
 *              @eg `1 * inch`
 *      @field endBoundEntity {Query} : @requiredif {`endBound` is `UP_TO_SURFACE` or `UP_TO_BODY`.}
 *              The face or body that provides the bound.
 *      @field startBound {BoundingType} : @optional
 *              The type of start bound. Default is for the extrude to start at `entities`. Cannot be `SYMMETRIC`.
 *      @field startDepth {ValueWithUnits} : @requiredif {`startBound` is `BLIND`.}
 *              How far from the `entities` to start the extrude.
 *      @field startBoundEntity {Query} : @requiredif {`startBound` is `UP_TO_SURFACE` or `UP_TO_BODY`.}
 *              The face or body that provides the bound.
 * }}
 */
export function opExtrude(context is Context, id is Id, definition is map)

Changing the sense convention is really annoying by the way.

Plus there is a bug if [-1*startDepth < endDepth < 0] ([-1*startDepth < 0 < endDepth] & [0 < -1*startDepth < endDepth] work fine as expected)

traveler_hauptman

// TODO: rename this to coordSystem(plane is Plane)?
export function planeToCSys(plane is Plane) returns CoordSystem

Yes please!

(but add a second function because I'm using this one now. Hurray legacy )

traveler_hauptman

The error:

Precondition (rhs == 0) of operator< failed

Was a little opaque. Maybe hint that there is probably a type mismatch?

I hit this comparing a number to another number (which was really a ValueWithUnits).

john_f_carr

traveler_hauptman said:

The error:

Precondition (rhs == 0) of operator< failed

Was a little opaque. Maybe hint that there is probably a type mismatch?

I hit this comparing a number to another number (which was really a ValueWithUnits).

Thanks for the feedback.  We'll be improving these messages.

ilya_baran

Agreed that opExtrude is confusing -- logged an issue and making a doc update in the meantime.

We really appreciate this feedback, thanks!