Miscellaneous documentation fixes

attic/multibody/collision/bullet_model.h

@@ -94,6 +94,7 @@ class BulletModel : public Model {
    * Computes the closest point in the collision world to each of a set of
    * points. For each query point, a PointPair instance, `p`, is returned with
    * the following semantics:
+   *
    *    - p.elementA = p.elementB = pointer to the closest element.
    *    - p.idA = p.idB = ElementId of closest element.
    *    - p.ptA = the point on the closest element's surface expressed and
@@ -104,6 +105,7 @@ class BulletModel : public Model {
    *        point, expressed in the world frame.
    *    - p.distance = The *signed* distance between the query point and the
    *        nearest point.  Negative values indicate penetration.
+   *
    * If there are no objects in the scene, then the pointers will be nullptr,
    * the ids, 0, the distance infinite, and the nearest points, infinitely far
    * away.

attic/multibody/rigid_body.h

@@ -25,7 +25,8 @@ class RigidBody {
   /**
    * Returns a clone of this RigidBody.
    *
-   * *Important note!* The following are not cloned:
+   * @attention The following are not cloned:
+   *
    *    - the joint
    *    - the parent %RigidBody
    *    - the visual elements
@@ -297,6 +298,7 @@ class RigidBody {
    * single inboard joint. This joint defines several frames, discussed in
    * @ref rigid_body_tree_frames, including its parent frame: `Pₖ ≡ Bₖ₋₁`. This
    * allows us to compute `X_Bₖ₋₁Bₖ` as follows:
+   *
    * - `X_Bₖ₋₁Bₖ = X_PₖBₖ` because `Pₖ ≡ Bₖ₋₁`
    * - `X_PₖBₖ ≡ X_PₖFₖ * X_FₖMₖ(q) * X_MₖBₖ`, where:
    *    - `X_MₖBₖ = I` in Drake's implementation.

attic/multibody/rigid_body_plant/compliant_material.h

@@ -58,6 +58,7 @@ class CompliantMaterial {
 
   /** Constructs fully specified material. Will throw an exception in any of the
    following circumstances:
+
      - `youngs_modulus` <= 0
      - `dissipation` < 0
      - `static_friction` < 0

attic/multibody/rigid_body_plant/contact_force.h

@@ -11,6 +11,7 @@ namespace systems {
 
  Ultimately, a contact force consists of an application point, a spatial
  force, and a unit vector. The spatial force includes:
+
     - a translational force, that is a pure force applied at a point,
     - a torque, the rotational force. This is not the same as the moment
       induced by the translational force.  This torque can arise from a

attic/multibody/rigid_body_plant/rigid_body_plant_bridge.h

@@ -33,6 +33,7 @@ namespace systems {
     - . : No geometry is used, shapes of this type are *ignored*
 
  The columns of the table indicate the SceneGraph roles.
+
    - Proximity: The shape is used in proximity queries (e.g., penetration,
                 distance, ray-casting, etc.)
    - Visual:    The shape is displayed in drake_visualizer.
@@ -48,6 +49,7 @@ namespace systems {
   %MeshPoints | .         | .      | .
   %Plane      | V         | V      | .
   %Sphere     | V         | V      | .
+
  <h4>Table: Level of Support. Indication of what types of shapes (rows) are read
  from the RigidBodyTree, the role they played in the RigidBodyTree, collision or
  visual, (cell values "C", "V", or ".") and how they are used in SceneGraph

common/copyable_unique_ptr.h

@@ -78,6 +78,7 @@ namespace drake {
  referenced object, such that the new copy contains an instance of `Base`
  instead of `Derived`. Some mistakes that would lead to this degenerate
  behavior:
+
    - The `Base` class has a public copy constructor.
    - The `Base` class's Clone() implementation does not invoke the `Derived`
    class's implementation of a suitable virtual method.

common/symbolic_formula_cell.h

@@ -372,6 +372,7 @@ class FormulaPositiveSemidefinite : public FormulaCell {
    * the two matrices `m1` in `psd1` and `m2` in `psd2`.
    *
    * First, we compare the size of `m1` and `m2`:
+   *
    * - If `m1` is smaller than `m2`, `psd1.Less(psd2)` is true.
    * - If `m2` is smaller than `m1`, `psd1.Less(psd2)` is false.
    *
@@ -389,7 +390,8 @@ class FormulaPositiveSemidefinite : public FormulaCell {
    * EXPECT_TRUE(psd1.Less(psd2));
    * @endcode
    *
-   * Note that in the code above, `psd1.Less(psd2)` holds because we have
+   * @note In the code above, `psd1.Less(psd2)` holds because we have
+   *
    *  - m1 in column-major ordering : (x + y)  -3.14   -3.14   y_
    *  - m2 in column-major ordering : (x + y)   3.14    3.14   y_.
    */

common/symbolic_rational_function.h

@@ -151,10 +151,12 @@ RationalFunction operator/(double c, const RationalFunction& f);
 RationalFunction pow(const RationalFunction& f, int n);
 /**
  *  Provides the following operations:
+ *
  *  - Matrix<RF>         * Matrix<Polynomial> => Matrix<RF>
  *  - Matrix<RF>         * Matrix<double>     => Matrix<RF>
  *  - Matrix<Polynomial> * Matrix<RF>         => Matrix<RF>
  *  - Matrix<double>     * Matrix<RF>         => Matrix<RF>
+ *
  * where RF is a shorthand for RationalFunction.
  *
  * @note that these operator overloadings are necessary even after providing

common/type_safe_index.h

@@ -327,8 +327,10 @@ class TypeSafeIndex {
   // without unsigned/signed comparison warnings (which Drake considers to be an
   // error). Furthermore, the SFINAE is necessary to prevent ambiguity.
   // Index == int can be resolved two ways:
-  //   - convert Index to int
-  //   - promote int to size_t
+  //
+  // - convert Index to int
+  // - promote int to size_t
+  //
   // SFINAE prevents the latter.
 
   /// Whitelist equality test with indices of this tag.

examples/kuka_iiwa_arm/pick_and_place/action.h

@@ -154,6 +154,7 @@ class WsgAction : public Action {
 
   /**
    * Returns true if the following criteria are satisfied:
+   *
    *  - The gripper speed is less than the final speed threshold.
    *  - 0.5 s have elapsed since the last Open/Close command was issued.
    *  - The gripper position is greater than (for an Open command) or less than

examples/rod2d/rod2d.h

@@ -25,26 +25,27 @@ standard multibody notation as described in detail here:
 <!-- https://drake.mit.edu/doxygen_cxx/group__multibody__notation.html -->
 
 For a quick summary and translation to 2D:
- - When we combine rotational and translational quantities into a single
-   quantity in 3D, we call those "spatial" quantities. In 2D those combined
-   quantities are actually planar, but we will continue to refer to them as
-   "spatial" to keep the notation analogous and promote easy extension of 2D
-   pedagogical examples to 3D.
- - We use capital letters to represent bodies and coordinate frames. Frame F has
-   an origin point Fo, and a basis formed by orthogonal unit vector axes Fx and
-   Fy, with an implicit `Fz=Fx × Fy` always pointing out of the screen for a 2D
-   system. The inertial frame World is W, and the rod frame is R.
- - We also use capitals to represent points, and we allow a frame name F to be
-   used where a point is expected to represent its origin Fo.
- - We use `p_CD` to represent the position vector from point C to point D. Note
-   that if A and B are frames, `p_AB` means `p_AoBo`.
- - If we need to be explicit about the expressed-in frame F for any quantity, we
-   add the suffix `_F` to its symbol. So the position vector from C to D,
-   expressed in W, is `p_CD_W`.
- - R_AB is the rotation matrix giving frame B's orientation in frame A.
- - X_AB is the transformation matrix giving frame B's pose in frame A, combining
-   both a rotation and a translation; this is conventionally called a
-   "transform". A transform is a spatial quantity.
+
+- When we combine rotational and translational quantities into a single
+  quantity in 3D, we call those "spatial" quantities. In 2D those combined
+  quantities are actually planar, but we will continue to refer to them as
+  "spatial" to keep the notation analogous and promote easy extension of 2D
+  pedagogical examples to 3D.
+- We use capital letters to represent bodies and coordinate frames. Frame F has
+  an origin point Fo, and a basis formed by orthogonal unit vector axes Fx and
+  Fy, with an implicit `Fz=Fx × Fy` always pointing out of the screen for a 2D
+  system. The inertial frame World is W, and the rod frame is R.
+- We also use capitals to represent points, and we allow a frame name F to be
+  used where a point is expected to represent its origin Fo.
+- We use `p_CD` to represent the position vector from point C to point D. Note
+  that if A and B are frames, `p_AB` means `p_AoBo`.
+- If we need to be explicit about the expressed-in frame F for any quantity, we
+  add the suffix `_F` to its symbol. So the position vector from C to D,
+  expressed in W, is `p_CD_W`.
+- R_AB is the rotation matrix giving frame B's orientation in frame A.
+- X_AB is the transformation matrix giving frame B's pose in frame A, combining
+  both a rotation and a translation; this is conventionally called a
+  "transform". A transform is a spatial quantity.
 
 In 2D, with frames A and B the above quantities are (conceptually) matrices
 with the indicated dimensions: <pre>
@@ -58,11 +59,12 @@ represented by (x,y,θ).
 
 We use v for translational velocity of a point and w (ω) for rotational
 velocity of a frame. The symbols are:
- - `v_AP` is point P's velocity in frame A, expressed in frame A if no
-   other frame is given as a suffix.
- - `w_AB` is frame B's angular velocity in frame A, expressed in frame A
-   if no other frame is given as a suffix.
- - `V_AB` is frame B's spatial velocity in A, meaning `v_ABo` and `w_AB`.
+
+- `v_AP` is point P's velocity in frame A, expressed in frame A if no
+  other frame is given as a suffix.
+- `w_AB` is frame B's angular velocity in frame A, expressed in frame A
+  if no other frame is given as a suffix.
+- `V_AB` is frame B's spatial velocity in A, meaning `v_ABo` and `w_AB`.
 
 
 These quantities are conceptually: <pre>
@@ -75,9 +77,10 @@ velocity with just the scalar w=ω=@f$\dot{\theta}@f$ (that is, d/dt θ), and
 spatial velocity as (vx,vy,ω).
 
 Forces f and torques τ are represented similarly:
- - `f_P` is an in-plane force applied to a point P fixed to some rigid body.
- - `t_A` is an in-plane torque applied to frame A (meaning it is about Az).
- - `F_A` is a spatial force including both `f_Ao` and `t_A`.
+
+- `f_P` is an in-plane force applied to a point P fixed to some rigid body.
+- `t_A` is an in-plane torque applied to frame A (meaning it is about Az).
+- `F_A` is a spatial force including both `f_Ao` and `t_A`.
 
 The above symbols can be suffixed with an expressed-in frame if the frame is
 not already obvious, so `F_A_W` is a spatial force applied to frame A (at Ao)
@@ -109,6 +112,7 @@ h, and "left" and "right" endpoints `Rl=Ro-h*Rx` and `Rr=Ro+h*Rx` at which
 it can contact the halfspace whose surface is at Wy=0.
 
 This system can be simulated using one of three models:
+
 - continuously, using a compliant contact model (the rod is rigid, but contact
   between the rod and the half-space is modeled as compliant) simulated using
   ordinary differential equations (ODEs),

examples/scene_graph/solar_system.h

@@ -31,10 +31,10 @@ namespace solar_system {
    Luna but at different relative angular positions around their axis of
    rotation.
  - Mars orbits the sun at a farther distance on a plane that is tilted off of
- the xy-plane. Its moon (Phobos) orbits around Mars on a plane parallel to
- Mars's orbital plane, but in the opposite direction.
+   the xy-plane. Its moon (Phobos) orbits around Mars on a plane parallel to
+   Mars's orbital plane, but in the opposite direction.
  - Mars has been given an arbitrary set of rings posed askew. The rings are
- declared as a child of mars's geometry.
+   declared as a child of mars's geometry.
 
  This system illustrates the following features:
 

geometry/dev/geometry_roles.h

@@ -106,6 +106,7 @@ namespace dev {
  Role assignment is achieved by assigning as set of role-related *properties*
  to a geometry (see SceneGraph::AssignRole()). The set *can* be empty. Each
  role has a specific property set associated with it:
+
    - __Proximity role__: ProximityProperties
    - __Perception role__: PerceptionProperties
    - __Illustration role__: IllustrationProperties

geometry/dev/geometry_visualization.h

@@ -37,6 +37,7 @@ class GeometryVisualizationImpl {
 
  This is a convenience method to simplify some common boilerplate for adding
  visualization capability to a Diagram. What it does is:
+
  - adds an initialization event that sends the required load message to set up
    the visualizer with the relevant geometry,
  - adds systems PoseBundleToDrawMessage and LcmPublisherSystem to

geometry/dev/render/render_label.h

@@ -74,6 +74,7 @@ namespace render {
  @cond
  NOTE: In many ways, this is very similar to the TypeSafeIndex class. There are
  several key differences:
+
    - added static members,
    - special values (empty and terrain),
    - arbitrarily limited domain (kLabelCount).

geometry/dev/scene_graph.h

@@ -51,6 +51,7 @@ class QueryObject;
  source owns, via a port connection on %SceneGraph.
 
  The basic workflow for interacting with %SceneGraph is:
+
    - Register as a geometry source, acquiring a unique SourceId.
    - Register geometry (anchored and dynamic) with the system.
    - Connect source's geometry output ports to the corresponding %SceneGraph

geometry/dev/scene_graph_inspector.h

@@ -19,24 +19,25 @@ class QueryObject;
  of the SceneGraph data that does *not* depend on input pose data. Including,
  but not limited to:
 
-   - names of frames and geometries
-   - hierarchies (parents of geometries, parents of frames, etc.)
-   - geometry parameters (e.g., contact, rendering, visualization)
-   - fixed poses of geometries relative to frames
+ - names of frames and geometries
+ - hierarchies (parents of geometries, parents of frames, etc.)
+ - geometry parameters (e.g., contact, rendering, visualization)
+ - fixed poses of geometries relative to frames
 
  In contrast, the following pieces of data *do* depend on input pose data and
  *cannot* be performed with the %SceneGraphInspector (see the QueryObject
  instead):
 
-   - world pose of frames or geometry
-   - collision queries
-   - proximity queries
+ - world pose of frames or geometry
+ - collision queries
+ - proximity queries
 
  A %SceneGraphInspector cannot be instantiated explicitly. Nor can it be copied
  or moved. A *reference* to a %SceneGraphInspector instance can be acquired from
-   - a SceneGraph instance (to inspect the state of the system's _model_), or
-   - a QueryObject instance (to inspect the state of the scene graph data stored
-     in the context).
+
+ - a SceneGraph instance (to inspect the state of the system's _model_), or
+ - a QueryObject instance (to inspect the state of the scene graph data stored
+   in the context).
 
  The reference should not be persisted (and, as previously indicated, cannot
  be copied). %SceneGraphInspector instances are cheap; they can be created,

geometry/geometry_frame.h

@@ -16,6 +16,7 @@ namespace geometry {
  over to SceneGraph.
 
  A frame is defined by three pieces of information:
+
     - the name, which must be unique within a single geometry source,
     - the "frame group", an integer identifier that can be used to group frames
       together within a geometry source, and

geometry/geometry_instance.h

@@ -23,6 +23,7 @@ namespace geometry {
  valid names in SDF files. Specifically, any user-specified name will have
  all leading and trailing space and tab characters trimmed off. The trimmed name
  will have to satisfy the following requirements:
+
    - cannot be empty, and
    - the name should be unique in the scope of its frame and role. For example,
      two GeometryInstances can both be called "ball" as long as they are
@@ -31,6 +32,7 @@ namespace geometry {
      but will be enforced in the future.
      <!-- TODO(SeanCurtis-TRI): When geometry roles lands, change this to
      indicate that this is enforced. -->
+
  If valid, the trimmed name will be assigned to the instance.
 
  Names *can* have internal whitespace (e.g., "my geometry name").

geometry/geometry_set.h

@@ -147,6 +147,7 @@ class GeometrySet {
 
    The interface for adding geometries to the set is simply an overload of the
    Add() method. For maximum flexibility, the Add method can take:
+
      - a single geometry id
      - a single frame id
      - an iterable object containing geometry ids

geometry/geometry_visualization.h

@@ -36,6 +36,7 @@ class GeometryVisualizationImpl {
 
  This is a convenience method to simplify some common boilerplate for adding
  visualization capability to a Diagram. What it does is:
+
  - adds an initialization event that sends the required load message to set up
    the visualizer with the relevant geometry,
  - adds systems PoseBundleToDrawMessage and LcmPublisherSystem to

geometry/scene_graph.h

@@ -48,12 +48,13 @@ class QueryObject;
  source owns, via a port connection on %SceneGraph.
 
  The basic workflow for interacting with %SceneGraph is:
-   - Register as a geometry source, acquiring a unique SourceId.
-   - Register geometry (anchored and dynamic) with the system.
-   - Connect source's geometry output ports to the corresponding %SceneGraph
-     input ports.
-     - Implement appropriate `Calc*` methods on the geometry output ports to
-       update geometry pose values.
+
+ - Register as a geometry source, acquiring a unique SourceId.
+ - Register geometry (anchored and dynamic) with the system.
+ - Connect source's geometry output ports to the corresponding %SceneGraph
+   input ports.
+   - Implement appropriate `Calc*` methods on the geometry output ports to
+     update geometry pose values.
 
  @section geom_sys_inputs Inputs
  @cond

geometry/scene_graph_inspector.h

@@ -17,24 +17,25 @@ class QueryObject;
  of the SceneGraph data that does *not* depend on input pose data. Including,
  but not limited to:
 
-   - names of frames and geometries
-   - hierarchies (parents of geometries, parents of frames, etc.)
-   - geometry parameters (e.g., contact, rendering, visualization)
-   - fixed poses of geometries relative to frames
+ - names of frames and geometries
+ - hierarchies (parents of geometries, parents of frames, etc.)
+ - geometry parameters (e.g., contact, rendering, visualization)
+ - fixed poses of geometries relative to frames
 
  In contrast, the following pieces of data *do* depend on input pose data and
  *cannot* be performed with the %SceneGraphInspector (see the QueryObject
  instead):
 
-   - world pose of frames or geometry
-   - collision queries
-   - proximity queries
+ - world pose of frames or geometry
+ - collision queries
+ - proximity queries
 
  A %SceneGraphInspector cannot be instantiated explicitly. Nor can it be copied
  or moved. A *reference* to a %SceneGraphInspector instance can be acquired from
-   - a SceneGraph instance (to inspect the state of the system's _model_), or
-   - a QueryObject instance (to inspect the state of the scene graph data stored
-     in the context).
+
+ - a SceneGraph instance (to inspect the state of the system's _model_), or
+ - a QueryObject instance (to inspect the state of the scene graph data stored
+   in the context).
 
  The reference should not be persisted (and, as previously indicated, cannot
  be copied). %SceneGraphInspector instances are cheap; they can be created,