fix typos and add comments

Author: baggepinnen

docs/src/examples/pendulum.md

@@ -1,5 +1,5 @@
 # Pendulum--The "Hello World of multi-body dynamics"
-This beginners tutorial will model a pendulum pivoted around the origin in the world frame. The world frame is a constant that lives inside the Multibody module, all multibody models are "grounded" in the same world, i.e., the `world` component must be included in all models.
+This beginners tutorial will start by modeling a pendulum pivoted around the origin in the world frame. The world frame is a constant that lives inside the Multibody module, all multibody models are "grounded" in the same world, i.e., the `world` component must be included in all models.
 
 To start, we load the required packages
 ```@example pendulum
@@ -12,11 +12,11 @@ We then access the world frame and time variable from the Multibody module
 ```@example pendulum
 t = Multibody.t
 world = Multibody.world
-show(stdout, MIME"text/plain"(), world)
+show(stdout, MIME"text/plain"(), world) # hide
 nothing # hide
 ```
 
-Unless otherwise specified, the world defaults to have a gravitational field pointing in the negative ``y`` direction and a gravitational acceleration of ``9.81``.
+Unless otherwise specified, the world defaults to having a gravitational field pointing in the negative ``y`` direction and a gravitational acceleration of ``9.81`` (See [Bodies in space](@ref) for more options).
 
 
 ## Modeling the pendulum
@@ -50,12 +50,12 @@ Before we can simulate the system, we must perform model compilation using [`str
 ```@example pendulum
 ssys = structural_simplify(IRSystem(model))
 ```
-This results in a simplified model with the minimum required variables and equations to be able to simulate the system efficiently. This step rewrites all `connect` statements into the appropriate equations, and removes any redundant variables and equations.
+This results in a simplified model with the minimum required variables and equations to be able to simulate the system efficiently. This step rewrites all `connect` statements into the appropriate equations, and removes any redundant variables and equations. To simulate the pendulum, we require two state variables, one for angle and one for angular velocity, we can see above that these state variables have indeed been chosen.
 
 We are now ready to create an `ODEProblem` and simulate it. We use the `Rodas4` solver from OrdinaryDiffEq.jl, and pass a dictionary for the initial conditions. We specify only initial condition for some variables, for those variables where no initial condition is specified, the default initial condition defined the model will be used.
 ```@example pendulum
 D = Differential(t)
-defs = Dict(D(joint.phi) => 0, D(D(joint.phi)) => 0)
+defs = Dict(D(joint.phi) => 0, D(D(joint.phi)) => 0) # We may specify the initial condition here
 prob = ODEProblem(ssys, defs, (0, 3.35))
 
 sol = solve(prob, Rodas4())

docs/src/examples/swing.md

@@ -70,13 +70,15 @@ prob = ODEProblem(ssys, [
 sol = solve(prob, ImplicitEuler(autodiff=false), reltol=5e-3)
 @assert SciMLBase.successful_retcode(sol)
 ```
-This makes for a rather interesting-looking springy pendulum!
 
 ```@example SWING
 import CairoMakie
 Multibody.render(model, sol; z = -5, filename = "simple_swing.gif") # Use "simple_swing.mp4" for a video file
 nothing # hide
 ```
+![animation](simple_swing.gif)
+This makes for a rather interesting-looking springy pendulum!
+
 
 Next, we create the full swing assembly
 

docs/src/index.md

@@ -159,7 +159,8 @@ The following animations give a quick overview of simple mechanisms that can be
 
 - The torque variable in Multibody.jl is typically called `tau` rather than `t` to not conflict with the often used independent variable `t` used to denote time.
 - Multibody.jl occasionally requires the user to specify which component should act as the root of the kinematic tree. This only occurs when bodies are connected directly to force components without a joint parallel to the force component.
-- In Multibody.jl, the orientation object of a [`Frame`](@ref) is accessed using he function [`ori`](@ref).
+- In Multibody.jl, the orientation object of a [`Frame`](@ref) is accessed using the function [`ori`](@ref).
+- Quaternions in Multibody.jl follow the order ``[s, i, j, k]``, i.e., scalar/real part first.
 
 
 

src/joints.jl

@@ -673,7 +673,7 @@ Note, that bodies such as [`Body`](@ref), [`BodyShape`](@ref), have potential st
 
 The state of the FreeMotion object consits of:
 
-The relative position vector `r_rel_a` from the origin of `frame_a` to the origin of `frame_b`, resolved in `frame_a` and the relative velocity `v_rel_a` of the origin of `frame_b` with respect to the origin of `frame_a`, resolved in `frame_a (= der(r_rel_a))`.
+The relative position vector `r_rel_a` from the origin of `frame_a` to the origin of `frame_b`, resolved in `frame_a` and the relative velocity `v_rel_a` of the origin of `frame_b` with respect to the origin of `frame_a`, resolved in `frame_a (= D(r_rel_a))`.
 
 # Arguments
 
@@ -722,9 +722,9 @@ The relative position vector `r_rel_a` from the origin of `frame_a` to the origi
         ]
         (v_rel_a(t)[1:3] = v_rel_a),
         [
-            description = "= der(r_rel_a), i.e., velocity of origin of frame_b with respect to origin of frame_a, resolved in frame_a",
+            description = "= D(r_rel_a), i.e., velocity of origin of frame_b with respect to origin of frame_a, resolved in frame_a",
         ]
-        (a_rel_a(t)[1:3] = a_rel_a), [description = "= der(v_rel_a)"]
+        (a_rel_a(t)[1:3] = a_rel_a), [description = "= D(v_rel_a)"]
     end
 
     @named Rrel_f = Frame()