Skip to content

Improve documentation for 3D primitives. - #73

Open
player-03 wants to merge 17 commits into
openfl:masterfrom
player-03:primitives_documentation
Open

player-03 wants to merge 17 commits into
openfl:masterfrom
player-03:primitives_documentation

Conversation

@player-03

Copy link
Copy Markdown
Collaborator
  • Using "section" instead of "segment" helps avoid confusion with LineSegment. This is mostly important for wireframe primitives, but I changed everything for consistency.
  • Describing the shape as being "divided into sections" along an axis helps make it clearer what the sections actually represent. It's only one data point, but I found it easy to interpret the old documentation backwards.
  • I described round shapes in terms of circumference and height, rather than width and height, because width could be interpreted as not wrapping around the shape.
  • I fixed some typos and incorrect descriptions.

This more clearly conveys the intended meaning, and is less likely to be confused with the line segments that make up a wireframe.
It was already clear enough, so the rewrite is purely for consistency.
Now using more accurate mathematical terminology. "Major circumference" might be questionable here, but it's close enough.
It was already clear enough, but now it's more consistent with the other primitives.
It was already clear enough, but this makes it more consistent.
Perhaps in AS3 these were supposed to be attached to the getter functions, but in Haxe, they should be attached to the property declarations.
@player-03

Copy link
Copy Markdown
Collaborator Author

An example of what I found confusing:

Two wireframe cylinders, with different sections highlighted on each.

On the left, the sections are vertical but correspond with the X axis (or circumference). On the right, the sections are horizontal but correspond with the Y axis.

The numbers indicate what's actually being counted: the number of times the section fits into the cylinder. sectionsC is 8, because the circumference is divided into 8 of those vertical sections. sectionsH is 4, because the height is divided into 4 of those ring-shaped sections. Hopefully, the new wording makes all this clearer, so no one else makes the same mistake I did.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant