Documentation cleanup (#278)

documentation cleanup

docs/api/classes/mousejoint.md

@@ -3,7 +3,7 @@
 # Class: MouseJoint
 
 A mouse joint is used to make a point on a body track a specified world
-point. This a soft constraint with a maximum force. This allows the
+point. This is a soft constraint with a maximum force. This allows the
 constraint to stretch and without applying huge forces.
 
 You need to call setTarget(target) every time that mouse is

docs/pages/api-conventions/factories-and-definitions.md

@@ -1,6 +1,6 @@
 ### Factories and Definitions
 
-To create a Body or a Joint, you need to call the factory functions on World:
+To create a `Body` or a `Joint`, you need to call the factory functions on World:
 
 ```js
 body = world.createBody(bodyDef);
@@ -21,14 +21,14 @@ the number of function parameters small, provide sensible defaults, and
 reduce the number of accessors.
 
 Since fixtures must be parented to a body, they are created and
-destroyed using a factory method on Body:
+destroyed using a factory method on `Body`:
 
 ```js
 let fixture = body.createFixture(fixtureDef);
 body.destroyFixture(fixture);
 ```
 
-There is also shortcut to create a fixture directly from the shape and
+There is also a shortcut to create a fixture directly from the shape and
 density.
 
 ```js

docs/pages/api-conventions/implicit-destruction.md

@@ -25,10 +25,10 @@ going to be implicitly destroyed.
 world.on('remove-joint', function(joint) {
  // remove all references to joint. 
 });
-world.on('remove-fixture', function(joint) {
+world.on('remove-fixture', function(fixture) {
  // remove all references to fixture.
 });
-world.on('remove-body', function(joint) {
+world.on('remove-body', function(body) {
  // bodies are not removed implicitly,
  // but the world publishes this event if a body is removed
 })

docs/pages/body.md

@@ -41,7 +41,7 @@ when you are done with them.
 
 #### Body Factory
 Bodies are created and destroyed using a body factory provided by the
-world class. This lets the world create the body and add the body to the 
+`World` class. This lets the world create the body and add the body to the 
 world data structure.
 
 ```js
@@ -68,7 +68,7 @@ manage shape and joint references.
 
 Let's go over some of the key members of the body definition.
 
-####3 Body Type
+##### Body Type
 As discussed at the beginning of this chapter, there are three different
 body types: static, kinematic, and dynamic. You should specify the
 body type at creation because changing the body type later is expensive.
@@ -94,8 +94,8 @@ A body has two main points of interest. The first point is the body's
 origin. Fixtures and joints are attached relative to the body's origin.
 The second point of interest is the center of mass. The center of mass
 is determined from mass distribution of the attached shapes or is
-explicitly set with MassData. Much of Planck.js's internal computations
-use the center of mass position. For example Body stores the linear
+explicitly set with `MassData`. Much of Planck.js's internal computations
+use the center of mass position. For example `Body` stores the linear
 velocity for the center of mass.
 
 When you are building the body definition, you may not know where the
@@ -315,7 +315,7 @@ body.isFixedRotation(); // boolean
 
 ##### Position and Velocity
 You can access the position and rotation of a body. This is common when
-rendering your associated game actor. You can also set the position,
+rendering your associated game actor. You can also set the position and rotation,
 although this is less common since you will normally use Planck.js to
 simulate movement.
 
@@ -373,14 +373,14 @@ if (myBody.isAwake()) {
 The body class has some utility functions to help you transform points
 and vectors between local and world space.
 
-A localPoint is a coordination relative to body's origin.
-A worldPoint is a coordination relative to world's origin.
+A `localPoint` is a coordinate relative to the body's origin.
+A `worldPoint` is a coordinate relative to the world's origin.
 
-A localVector is a vector between two points relative to body's origin.
-A worldVector is a vector between two points relative to world's origin.
+A `localVector` is a vector between two points relative to the body's origin.
+A `worldVector` is a vector between two points relative to the world's origin.
 
-Here point means a point's 2D coordination, vector means the vector between two points.
-In point conversion both position and angel of body are considered, in vector conversion only angle.
+Here "point" means a point's 2D coordinate, "vector" means the vector between two points.
+In point conversion both position and angle of body are considered, in vector conversion only angle.
 
 ```js
 body.getWorldPoint(localPoint); // Vec2

docs/pages/collision.md

@@ -1,5 +1,5 @@
 ### Collision
-The Collision classes includes shapes and functions that operate on them.
+The Collision classes include shapes and functions that operate on them.
 The module also contains a dynamic tree and broad-phase to acceleration
 collision processing of large systems.
 
@@ -25,15 +25,15 @@ improve stacking stability.
 Normally you don't need to compute contact manifolds directly, however
 you will likely use the results produced in the simulation.
 
-The Manifold structure holds a normal vector and up to two contact
+The `Manifold` structure holds a normal vector and up to two contact
 points. The normal and points are held in local coordinates. As a
 convenience for the contact solver, each point stores the normal and
 tangential (friction) impulses.
 
-The data stored in Manifold is optimized for internal use. If you need
-this data, it is usually best to use the WorldManifold structure to
+The data stored in `Manifold` is optimized for internal use. If you need
+this data, it is usually best to use the `WorldManifold` structure to
 generate the world coordinates of the contact normal and points. You
-need to provide a Manifold and the shape transforms and radii.
+need to provide a `Manifold` and the shape transforms and radii.
 
 ```js
 let worldManifold = manifold.getWorldManifold(null, transformA, shapeA.m_radius, transformB, shapeB.m_radius)
@@ -48,7 +48,7 @@ Notice that the world manifold uses the point count from the original
 manifold.
 
 During simulation shapes may move and the manifolds may change. Points
-may be added or removed. You can detect this using GetPointStates.
+may be added or removed. You can detect this using `GetPointStates()`.
 
 ```js
 let state1 = []; // [PointState]
@@ -63,7 +63,7 @@ if (state1[0] == PointState.removeState) {
 #### Distance
 The `Distance` function can be used to compute the distance between two
 shapes. The distance function needs both shapes to be converted into a
-DistanceProxy. There is also some caching used to warm start the
+`DistanceProxy`. There is also some caching used to warm start the
 distance function for repeated calls.
 
 ![Distance Function](./images/distance.svg)
@@ -99,15 +99,15 @@ may be cases where collisions are missed for small rotations. Normally,
 these missed rotational collisions should not harm game play. They tend
 to be glancing collisions.
 
-The function requires two shapes (converted to DistanceProxy) and two
-Sweep structures. The sweep structure defines the initial and final
+The function requires two shapes (converted to `DistanceProxy`) and two
+`Sweep` structures. The sweep structure defines the initial and final
 transforms of the shapes.
 
 You can use fixed rotations to perform a *shape cast*. In this case, the
 time of impact function will not miss any collisions.
 
 ### Dynamic Tree
-The DynamicTree class is used by Planck.js to organize large numbers of
+The `DynamicTree` class is used by Planck.js to organize large numbers of
 shapes efficiently. The class does not know about shapes. Instead it
 operates on axis-aligned bounding boxes (AABBs) with user data pointers.
 
@@ -133,7 +133,7 @@ be skipped.
 ![Overlap Test](./images/overlap_test.svg)
 
 Normally you will not use the dynamic tree directly. Rather you will go
-through the World class for ray casts and region queries. If you plan
+through the `World` class for ray casts and region queries. If you plan
 to instantiate your own dynamic tree, you can learn how to use it by
 looking at how Planck.js uses it.
 
@@ -143,7 +143,7 @@ and broad-phase. In the narrow-phase we compute contact points between
 pairs of shapes. Imagine we have N shapes. Using brute force, we would
 need to perform the narrow-phase for N*N/2 pairs.
 
-The BroadPhase class reduces this load by using a dynamic tree for
+The `BroadPhase` class reduces this load by using a dynamic tree for
 pair management. This greatly reduces the number of narrow-phase calls.
 
 Normally you do not interact with the broad-phase directly. Instead,

docs/pages/core-concepts.md

@@ -5,10 +5,10 @@ document.
 
 #### World
 A physics world is a collection of bodies, fixtures, and constraints that interact together.
-World also manages running simulation.
+`World` also manages running simulation.
 
 #### Shape
-A shape is 2D geometrical object, such as a circle or polygon.
+A shape is a 2D geometrical object, such as a circle or polygon.
 
 #### Rigid Body
 A chunk of matter that is so strong that the distance between any two bits of matter on the chunk is constant.
@@ -27,7 +27,7 @@ At this point the body can only rotate about the pin, so the constraint has remo
 
 #### Contact Constraint
 A special constraint designed to prevent penetration of rigid bodies and to simulate friction and restitution.
-You do not create contact constraints; they are created automatically by when two objects might collide.
+You do not create contact constraints; they are created automatically when two objects might collide.
 
 #### Joint
 This is a constraint used to hold two or more bodies together. There are several joint types implemented in the library: revolute, prismatic, distance, and more.

docs/pages/fixture.md

@@ -1,6 +1,6 @@
 ### Fixture
-Shapes are only have geometrical coordination, they don't have physical properties and don't know about body's transformation, so may be used independently of the physics simulation.
-Fixture class is used to attach shapes to bodies. A body may have zero or more fixtures. A
+Shapes only have geometrical coordinates, they don't have physical properties and don't know about the body's transformation, so may be used independently of the physics simulation.
+The `Fixture` class is used to attach shapes to bodies. A body may have zero or more fixtures. A
 body with multiple fixtures is sometimes called a *compound body.*
 
 Fixtures hold the following:
@@ -145,8 +145,8 @@ Collision groups let you specify an integral group index. You can have
 all fixtures with the same group index always collide (positive index)
 or never collide (negative index). Group indices are usually used for
 things that are somehow related, like the parts of a bicycle. In the
-following example, fixture1 and fixture2 always collide, but fixture3
-and fixture4 never collide.
+following example, `fixture1` and `fixture2` always collide, but `fixture3`
+and `fixture4` never collide.
 
 ```js
 fixture1Def.filterGroupIndex = 2;
@@ -156,7 +156,7 @@ fixture4Def.filterGroupIndex = -8;
 ```
 
 Collisions between fixtures of different group indices are filtered
-according the category and mask bits. In other words, group filtering
+according to the category and mask bits. In other words, group filtering
 has higher precedence than category filtering.
 
 Note that additional collision filtering occurs in Planck.js. Here is a

docs/pages/hello-world.md

@@ -1,12 +1,12 @@
 ### Getting Started
 
-In this section we will walk through a simple example to sets up the physics world, and creates a platform and a small box.
+In this section we will walk through a simple example to set up the physics world, and create a platform and a small box.
 
 #### Creating a World
 Every Planck.js program begins with the creation of a World object.
 World is the physics hub that manages objects, their physical interactions, and runs simulation.
 
-To create a world we simply create an object from World class, and optionally pass gravity.
+To create a world we simply create an object from the `World` class, and optionally pass gravity.
 
 ```js
 let world = new World({
@@ -21,9 +21,9 @@ Now that we have our physics world set up, let's start adding some stuff to it.
 We will create a platform using the following steps:
 
 1. Use the world object to create the body with position.
-1. Create a fixtures on the body with a shape.
+1. Create a fixture on the body with a shape.
 
-For the step 1, we pass body properties to the world object to create the platform body.
+For step 1, we pass body properties to the world object to create the platform body.
 With the body properties we specify the type and initial position of the platform:
 
 ```js
@@ -36,7 +36,7 @@ let platform = world.createBody({
 
 Bodies are "static" by default. Static bodies don't collide with other static bodies and are immovable.
 
-For the step 2, we need to create a Shape and add it to body as Fixture.
+For step 2, we need to create a `Shape` and add it to body as `Fixture`.
 
 ```js
 platform.createFixture({
@@ -45,10 +45,10 @@ platform.createFixture({
 ```
 
 Shapes only have geometrical properties (such as vertices or radius), and do not have physical properties.
-A fixture is used to add a shape to a body, and adds physical properties (such as density, friction, etc) to a body.
+A fixture is used to add a shape to a body, and adds physical properties (such as density, friction, etc.) to a body.
 A body can have any number of shapes fixed together.
 
-Shape's geometrical coordinates are local to the body. A fixture does not have location and angle. So when a body moves, all fixtures/shapes in the body move with the body. However we don't move a shape around on the body.
+`Shape`'s geometrical coordinates are local to the body. A fixture does not have location and angle. So when a body moves, all fixtures/shapes in the body move with the body. However we don't move a shape around on the body.
 
 Planck.js is a rigid body engine and many of the assumptions made in Planck.js are based on the rigid body model.
 A body with morphing shapes is not a rigid body, and if this is violated many things will break.
@@ -58,12 +58,12 @@ Every fixture must have a parent body, even fixtures that are static.
 However, you can attach all static fixtures to a single static body.
 
 A static body has zero mass by definition, so we don't need to specify density in this case.
-Later we will see how to use a fixture properties to customize its physical behavior.
+Later we will see how to use a fixture's properties to customize its physical behavior.
 
 #### Creating a dynamic box
 Creating a dynamic box is similar to the platform. The main difference, besides dimensions, is that for a dynamic body we need to specify mass properties.
 
-First we create the body using createBody. By default bodies are static, so we should set the body's `type` at construction time to make the body dynamic.
+First we create the body using `createBody`. By default bodies are static, so we should set the body's `type` at construction time to make the body dynamic.
 
 ```js
 let body = world.createBody({
@@ -99,5 +99,5 @@ So in this case the ground box is 2 units wide (x-axis) and 2 units tall (y-axis
 Planck.js by default is tuned for meters, kilograms, and seconds. So you can consider the dimensions to be in meters.
 Planck.js generally works best when objects are the size of typical real world objects. For example, a barrel is about 1 meter tall.
 Due to the limitations of floating point arithmetic, using Planck.js to model the movement of glaciers or dust particles is not a good idea.
-If you use a different units for your objects, you can change value of `Settings.lengthUnitsPerMeter`.
+If you use a different units for your objects, you can change the value of `Settings.lengthUnitsPerMeter`.
 For example if you use pixels and a barrel height is 80 pixels set the `lengthUnitsPerMeter` to 80.

docs/pages/index.md

@@ -1,13 +1,13 @@
 #### Planck.js
 
-Planck.js is JavaScript/TypeScript rewrite of Box2D C++ physics engine for cross-platform game development.
+Planck.js is JavaScript/TypeScript rewrite of the [Box2D](https://box2d.org/) C++ physics engine for cross-platform game development.
 
 #### Box2D
 
 Box2D is a 2D rigid-body physics simulation library for games. You can use it in your games to make objects move in realistic ways and make the game world more interactive.
 From the game engine's point of view, a physics engine is just a system for procedural animation.
 
-Planck.js documentation is based on Box2D manual with adjustments and addition for JavaScript. Both projects names are used interchangeably in the documentation.
+Planck.js documentation is based on the Box2D manual with adjustments and additions for JavaScript. Both projects' names are used interchangeably in the documentation.
 
 #### Before You Start
 

docs/pages/install.md

@@ -17,7 +17,7 @@ const world = new World();
 Planck.js is available on [jsDelivr](https://www.jsdelivr.com/package/npm/planck), [cdnjs](https://cdnjs.com/libraries/planck), and [unpkg](https://unpkg.com/planck/).
 
 ```html
- <script src="https://cdn.jsdelivr.net/npm/planck/dist/planck.min.js" />
+ <script src="https://cdn.jsdelivr.net/npm/planck/dist/planck.min.js"></script>
  <script>
  const { World } = planck;
  const world = new World();
@@ -41,7 +41,11 @@ testbed.start(world);
 
 ```html
 <html><body>
- <script src="https://cdn.jsdelivr.net/npm/planck/dist/planck-with-testbed.min.js" />
+ <span id="testbed-info"></span>
+ <span id="testbed-status"></span>
+ <button id="testbed-play">Play</button>
+
+ <script src="https://cdn.jsdelivr.net/npm/planck/dist/planck-with-testbed.min.js"></script>
  <script>
  const { World, Testbed } = planck;
  const world = new World();

docs/pages/joint.md

@@ -4,7 +4,7 @@ Typical examples in games include ragdolls, teeters, and pulleys. Joints
 can be combined in many different ways to create interesting motions.
 
 Some joints provide limits so you can control the range of motion. Some
-joint provide motors which can be used to drive the joint at a
+joints provide motors which can be used to drive the joint at a
 prescribed speed until a prescribed force/torque is exceeded.
 
 Joint motors can be used in many ways. You can use motors to control
@@ -17,14 +17,14 @@ too strong.
 
 ### Joint Definition
 Each joint type has a definition that derives from JointDef. All
-joints are connected between two different bodies. One body may static.
+joints are connected between two different bodies. One body may be static.
 Joints between static and/or kinematic bodies are allowed, but have no
 effect and use some processing time.
 
 You can specify user data for any joint type and you can provide a flag
 to prevent the attached bodies from colliding with each other. This is
-actually the default behavior and you must set the collideConnected
-to `true` to allow collision between to connected bodies.
+actually the default behavior and you must set `collideConnected`
+to `true` to allow collision between two connected bodies.
 
 Many joint definitions require that you provide some geometric data.
 Often a joint will be defined by anchor points. These are points fixed
@@ -35,8 +35,8 @@ occurrence when a game is saved and reloaded. Additionally, some joint
 definitions need to know the default relative angle between the bodies.
 This is necessary to constrain rotation correctly.
 
-[Initializing the geometric data can be tedious, so many joints have
-constructor that use the current body transforms to remove
+Initializing the geometric data can be tedious, so many joints have a
+constructor that uses the current body transforms to remove
 much of the work. However, these initialization functions should usually
 only be used for prototyping. Production code should define the geometry
 directly. This will make joint behavior more robust.
@@ -66,7 +66,7 @@ myWorld.destroyJoint(joint);
 joint = null;
 ```
 
-It is always good to nullify your variable after they are destroyed. This
+It is always good to nullify your variables after they are destroyed. This
 will make the program crash in a controlled manner if you try to reuse
 the variable.