Improve docstrings

Swigged python docstrings now include documented return values and type information or their arguments. They are generated in numpydoc format. Furthermore, all of the Python app layer docstrings have been changed to numpydoc format. The filterPythonFiles.py script which helps to generate the Doxygen Python API docs has been updated to reflect these changes.

Improve docstrings
Swigged python docstrings now include documented return values and type information or their arguments. They are generated in numpydoc format. Furthermore, all of the Python app layer docstrings have been changed to numpydoc format. The filterPythonFiles.py script which helps to generate the Doxygen Python API docs has been updated to reflect these changes.
98d053d4 · Robert McGibbon · 596a4197 · 98d053d4 · 98d053d4 · 98d053d4
Commit 98d053d4 authored Oct 30, 2015 by Robert McGibbon
20 changed files
--- a/openmmapi/include/openmm/CMAPTorsionForce.h
+++ b/openmmapi/include/openmm/CMAPTorsionForce.h
@@ -85,8 +85,8 @@ public:
     * Get the energy values of a map.
     *
     * @param index        the index of the map for which to get energy values
-     * @param size    the size of the map along each dimension
+     * @param[out] size    the size of the map along each dimension
-     * @param energy  the energy values for the map.  This must be of length size*size.
+     * @param[out] energy  the energy values for the map.  This must be of length size*size.
     *                     The element energy[i+size*j] contains the energy when the first
     *                     torsion angle equals i*2*PI/size and the second torsion angle
     *                     equals j*2*PI/size.
@@ -122,15 +122,15 @@ public:
     * Get the force field parameters for a CMAP torsion term.
     *
     * @param index      the index of the torsion for which to get parameters
-     * @param map   the index of the map to use for this term
+     * @param[out] map   the index of the map to use for this term
-     * @param a1    the index of the first particle forming the first torsion
+     * @param[out] a1    the index of the first particle forming the first torsion
-     * @param a2    the index of the second particle forming the first torsion
+     * @param[out] a2    the index of the second particle forming the first torsion
-     * @param a3    the index of the third particle forming the first torsion
+     * @param[out] a3    the index of the third particle forming the first torsion
-     * @param a4    the index of the fourth particle forming the first torsion
+     * @param[out] a4    the index of the fourth particle forming the first torsion
-     * @param b1    the index of the first particle forming the second torsion
+     * @param[out] b1    the index of the first particle forming the second torsion
-     * @param b2    the index of the second particle forming the second torsion
+     * @param[out] b2    the index of the second particle forming the second torsion
-     * @param b3    the index of the third particle forming the second torsion
+     * @param[out] b3    the index of the third particle forming the second torsion
-     * @param b4    the index of the fourth particle forming the second torsion
+     * @param[out] b4    the index of the fourth particle forming the second torsion
     */
    void getTorsionParameters(int index, int& map, int& a1, int& a2, int& a3, int& a4, int& b1, int& b2, int& b3, int& b4) const;
    /**

--- a/openmmapi/include/openmm/CustomAngleForce.h
+++ b/openmmapi/include/openmm/CustomAngleForce.h
@@ -159,7 +159,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -176,10 +176,10 @@ public:
     * Get the force field parameters for an angle term.
     *
     * @param index              the index of the angle for which to get parameters
-     * @param particle1     the index of the first particle connected by the angle
+     * @param[out] particle1     the index of the first particle connected by the angle
-     * @param particle2     the index of the second particle connected by the angle
+     * @param[out] particle2     the index of the second particle connected by the angle
-     * @param particle3     the index of the third particle connected by the angle
+     * @param[out] particle3     the index of the third particle connected by the angle
-     * @param parameters    the list of parameters for the angle
+     * @param[out] parameters    the list of parameters for the angle
     */
    void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, std::vector<double>& parameters) const;
    /**

--- a/openmmapi/include/openmm/CustomBondForce.h
+++ b/openmmapi/include/openmm/CustomBondForce.h
@@ -159,7 +159,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -175,9 +175,9 @@ public:
     * Get the force field parameters for a bond term.
     *
     * @param      index         the index of the bond for which to get parameters
-     * @param particle1     the index of the first particle connected by the bond
+     * @param[out] particle1     the index of the first particle connected by the bond
-     * @param particle2     the index of the second particle connected by the bond
+     * @param[out] particle2     the index of the second particle connected by the bond
-     * @param parameters    the list of parameters for the bond
+     * @param[out] parameters    the list of parameters for the bond
     */
    void getBondParameters(int index, int& particle1, int& particle2, std::vector<double>& parameters) const;
    /**

--- a/openmmapi/include/openmm/CustomCentroidBondForce.h
+++ b/openmmapi/include/openmm/CustomCentroidBondForce.h
@@ -226,7 +226,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -242,8 +242,8 @@ public:
     * Get the properties of a group.
     *
     * @param index            the index of the group to get
-     * @param particles   the indices of the particles in the group
+     * @param[out] particles   the indices of the particles in the group
-     * @param weights     the weight used for each particle when computing the center position.
+     * @param[out] weights     the weight used for each particle when computing the center position.
     *                         If no weights were specified, this vector will be empty indicating that particle
     *                         masses should be used as weights.
     */
@@ -269,8 +269,8 @@ public:
     * Get the properties of a bond.
     *
     * @param      index       the index of the bond to get
-     * @param groups      the indices of the groups in the bond
+     * @param[out] groups      the indices of the groups in the bond
-     * @param parameters  the list of per-bond parameter values for the bond
+     * @param[out] parameters  the list of per-bond parameter values for the bond
     */
    void getBondParameters(int index, std::vector<int>& groups, std::vector<double>& parameters) const;
    /**

--- a/openmmapi/include/openmm/CustomCompoundBondForce.h
+++ b/openmmapi/include/openmm/CustomCompoundBondForce.h
@@ -209,7 +209,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -224,8 +224,8 @@ public:
     * Get the properties of a bond.
     *
     * @param index            the index of the bond to get
-     * @param particles   the indices of the particles in the bond
+     * @param[out] particles   the indices of the particles in the bond
-     * @param parameters  the list of per-bond parameter values for the bond
+     * @param[out] parameters  the list of per-bond parameter values for the bond
     */
    void getBondParameters(int index, std::vector<int>& particles, std::vector<double>& parameters) const;
    /**

--- a/openmmapi/include/openmm/CustomExternalForce.h
+++ b/openmmapi/include/openmm/CustomExternalForce.h
@@ -170,7 +170,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -185,8 +185,8 @@ public:
     * Get the force field parameters for a force field term.
     *
     * @param index              the index of the particle term for which to get parameters
-     * @param particle      the index of the particle this term is applied to
+     * @param[out] particle      the index of the particle this term is applied to
-     * @param parameters    the list of parameters for the force field term
+     * @param[out] parameters    the list of parameters for the force field term
     */
    void getParticleParameters(int index, int& particle, std::vector<double>& parameters) const;
    /**

--- a/openmmapi/include/openmm/CustomGBForce.h
+++ b/openmmapi/include/openmm/CustomGBForce.h
@@ -309,7 +309,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index         the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue  the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -324,7 +324,7 @@ public:
     * Get the nonbonded force parameters for a particle.
     *
     * @param index            the index of the particle for which to get parameters
-     * @param parameters  the list of parameters for the specified particle
+     * @param[out] parameters  the list of parameters for the specified particle
     */
    void getParticleParameters(int index, std::vector<double>& parameters) const;
    /**
@@ -355,8 +355,8 @@ public:
     * Get the properties of a computed value.
     *
     * @param index            the index of the computed value for which to get parameters
-     * @param name        the name of the value
+     * @param[out] name        the name of the value
-     * @param expression  an algebraic expression to evaluate when calculating the computed value.  If the
+     * @param[out] expression  an algebraic expression to evaluate when calculating the computed value.  If the
     *                         ComputationType is SingleParticle, the expression is evaluated independently
     *                         for each particle, and may depend on its x, y, and z coordinates, as well as the per-particle
     *                         parameters and previous computed values for that particle.  If the ComputationType is ParticlePair
@@ -366,7 +366,7 @@ public:
     *                         the per-particle parameters and previous computed values for each of them.
     *                         Append "1" to a variable name to indicate the parameter for the particle whose
     *                         value is being calculated, and "2" to indicate the particle it is interacting with.
-     * @param type        the method to use for computing this value
+     * @param[out] type        the method to use for computing this value
     */
    void getComputedValueParameters(int index, std::string& name, std::string& expression, ComputationType& type) const;
    /**
@@ -407,7 +407,7 @@ public:
     * Get the properties of a term to the energy computation.
     *
     * @param index            the index of the term for which to get parameters
-     * @param expression  an algebraic expression to evaluate when calculating the energy.  If the
+     * @param[out] expression  an algebraic expression to evaluate when calculating the energy.  If the
     *                         ComputationType is SingleParticle, the expression is evaluated once
     *                         for each particle, and may depend on its x, y, and z coordinates, as well as the per-particle
     *                         parameters and computed values for that particle.  If the ComputationType is ParticlePair or
@@ -417,7 +417,7 @@ public:
     *                         the per-particle parameters and computed values for each of them.
     *                         Append "1" to a variable name to indicate the parameter for the first particle
     *                         in the pair and "2" to indicate the second particle in the pair.
-     * @param type        the method to use for computing this value
+     * @param[out] type        the method to use for computing this value
     */
    void getEnergyTermParameters(int index, std::string& expression, ComputationType& type) const;
    /**
@@ -449,8 +449,8 @@ public:
     * Get the particles in a pair whose interaction should be excluded.
     *
     * @param index           the index of the exclusion for which to get particle indices
-     * @param particle1  the index of the first particle in the pair
+     * @param[out] particle1  the index of the first particle in the pair
-     * @param particle2  the index of the second particle in the pair
+     * @param[out] particle2  the index of the second particle in the pair
     */
    void getExclusionParticles(int index, int& particle1, int& particle2) const;
    /**

--- a/openmmapi/include/openmm/CustomHbondForce.h
+++ b/openmmapi/include/openmm/CustomHbondForce.h
@@ -282,7 +282,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -301,12 +301,12 @@ public:
     * Get the properties of a donor group.
     *
     * @param index            the index of the donor group to get
-     * @param d1          the index of the first particle for this donor group
+     * @param[out] d1          the index of the first particle for this donor group
-     * @param d2          the index of the second particle for this donor group.  If the group only
+     * @param[out] d2          the index of the second particle for this donor group.  If the group only
     *                         includes one particle, this will be -1.
-     * @param d3          the index of the third particle for this donor group.  If the group includes
+     * @param[out] d3          the index of the third particle for this donor group.  If the group includes
     *                         less than three particles, this will be -1.
-     * @param parameters  the list of per-donor parameter values for the donor
+     * @param[out] parameters  the list of per-donor parameter values for the donor
     */
    void getDonorParameters(int index, int& d1, int& d2, int& d3, std::vector<double>& parameters) const;
    /**
@@ -337,12 +337,12 @@ public:
     * Get the properties of an acceptor group.
     *
     * @param index            the index of the acceptor group to get
-     * @param a1          the index of the first particle for this acceptor group
+     * @param[out] a1          the index of the first particle for this acceptor group
-     * @param a2          the index of the second particle for this acceptor group.  If the group only
+     * @param[out] a2          the index of the second particle for this acceptor group.  If the group only
     *                         includes one particle, this will be -1.
-     * @param a3          the index of the third particle for this acceptor group.  If the group includes
+     * @param[out] a3          the index of the third particle for this acceptor group.  If the group includes
     *                         less than three particles, this will be -1.
-     * @param parameters  the list of per-acceptor parameter values for the acceptor
+     * @param[out] parameters  the list of per-acceptor parameter values for the acceptor
     */
    void getAcceptorParameters(int index, int& a1, int& a2, int& a3, std::vector<double>& parameters) const;
    /**
@@ -369,16 +369,16 @@ public:
     * Get the donor and acceptor in a pair whose interaction should be excluded.
     *
     * @param index           the index of the exclusion for which to get donor and acceptor indices
-     * @param particle1  the index of the donor
+     * @param[out] particle1  the index of the donor
-     * @param particle2  the index of the acceptor
+     * @param[out] particle2  the index of the acceptor
     */
    void getExclusionParticles(int index, int& donor, int& acceptor) const;
    /**
     * Get the donor and acceptor in a pair whose interaction should be excluded.
     *
     * @param index      the index of the exclusion for which to get donor and acceptor indices
-     * @param particle1  the index of the donor
+     * @param donor      the index of the donor
-     * @param particle2  the index of the acceptor
+     * @param acceptor   the index of the acceptor
     */
    void setExclusionParticles(int index, int donor, int acceptor);
    /**

--- a/openmmapi/include/openmm/CustomIntegrator.h
+++ b/openmmapi/include/openmm/CustomIntegrator.h
@@ -371,7 +371,7 @@ public:
     * Get the value of a per-DOF variable, specified by name.
     *
     * @param name         the name of the variable to get
-     * @param values  the values of the variable for all degrees of freedom
+     * @param[out] values  the values of the variable for all degrees of freedom
     *                     are stored into this
     */
    void getPerDofVariableByName(const std::string& name, std::vector<Vec3>& values) const;
@@ -446,7 +446,7 @@ public:
    /**
     * Add a step which begins a new "if" block.
     *
-     * @param expression  a mathematical expression involving a comparison operator
+     * @param condition   a mathematical expression involving a comparison operator
     *                    and global variables.  All steps between this one and
     *                    the end of the block are executed only if the condition
     *                    is true.
@@ -457,7 +457,7 @@ public:
    /**
     * Add a step which begins a new "while" block.
     *
-     * @param expression  a mathematical expression involving a comparison operator
+     * @param condition   a mathematical expression involving a comparison operator
     *                    and global variables.  All steps between this one and
     *                    the end of the block are executed repeatedly as long as
     *                    the condition remains true.
@@ -476,12 +476,13 @@ public:
     * Get the details of a computation step that has been added to the integration algorithm.
     *
     * @param      index       the index of the computation step to get
-     * @param type       on exit, the type of computation this step performs
+     * @param[out] type        the type of computation this step performs
-     * @param variable   on exit, the variable into which this step stores its result.  If this
+     * @param[out] variable    the variable into which this step stores its
-     *                   step does not store a result in a variable, this will be an
+     *                         result.  If this step does not store a result in
-     *                   empty string.
+     *                         a variable, this will be an empty string.
-     * @param expression on exit, the expression this step evaluates.  If this step does not
+     * @param[out] expression  the expression this step evaluates.  If
-     *                   evaluate an expression, this will be an empty string.
+     *                         this step does not evaluate an expression, this
+     *                         will be an empty string.
     */
    void getComputationStep(int index, ComputationType& type, std::string& variable, std::string& expression) const;
    /**

--- a/openmmapi/include/openmm/CustomManyParticleForce.h
+++ b/openmmapi/include/openmm/CustomManyParticleForce.h
@@ -337,7 +337,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -353,8 +353,8 @@ public:
     * Get the nonbonded force parameters for a particle.
     *
     * @param index            the index of the particle for which to get parameters
-     * @param parameters  the list of parameters for the specified particle
+     * @param[out] parameters  the list of parameters for the specified particle
-     * @param type        the type of the specified particle
+     * @param[out] type        the type of the specified particle
     */
    void getParticleParameters(int index, std::vector<double>& parameters, int& type) const;
    /**
@@ -379,8 +379,8 @@ public:
     * Get the particles in a pair whose interaction should be excluded.
     *
     * @param index           the index of the exclusion for which to get particle indices
-     * @param particle1  the index of the first particle in the pair
+     * @param[out] particle1  the index of the first particle in the pair
-     * @param particle2  the index of the second particle in the pair
+     * @param[out] particle2  the index of the second particle in the pair
     */
    void getExclusionParticles(int index, int& particle1, int& particle2) const;
    /**
@@ -406,7 +406,7 @@ public:
     * regardless of the type of the specified particle.
     *
     * @param index         the index of the particle within the interaction (between 0 and getNumParticlesPerSet())
-     * @param types    the allowed types for the specified particle
+     * @param[out] types    the allowed types for the specified particle
     */
    void getTypeFilter(int index, std::set<int>& types) const;
    /**

--- a/openmmapi/include/openmm/CustomNonbondedForce.h
+++ b/openmmapi/include/openmm/CustomNonbondedForce.h
@@ -318,7 +318,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -333,7 +333,7 @@ public:
     * Get the nonbonded force parameters for a particle.
     *
     * @param index            the index of the particle for which to get parameters
-     * @param parameters  the list of parameters for the specified particle
+     * @param[out] parameters  the list of parameters for the specified particle
     */
    void getParticleParameters(int index, std::vector<double>& parameters) const;
    /**
@@ -357,8 +357,8 @@ public:
     * Get the particles in a pair whose interaction should be excluded.
     *
     * @param index           the index of the exclusion for which to get particle indices
-     * @param particle1  the index of the first particle in the pair
+     * @param[out] particle1  the index of the first particle in the pair
-     * @param particle2  the index of the second particle in the pair
+     * @param[out] particle2  the index of the second particle in the pair
     */
    void getExclusionParticles(int index, int& particle1, int& particle2) const;
    /**
@@ -441,8 +441,8 @@ public:
     * Get the parameters for an interaction group.
     *
     * @param index        the index of the interaction group for which to get parameters
-     * @param set1    the first set of particles forming the interaction group
+     * @param[out] set1    the first set of particles forming the interaction group
-     * @param set2    the second set of particles forming the interaction group
+     * @param[out] set2    the second set of particles forming the interaction group
     */
    void getInteractionGroupParameters(int index, std::set<int>& set1, std::set<int>& set2) const;
    /**

--- a/openmmapi/include/openmm/CustomTorsionForce.h
+++ b/openmmapi/include/openmm/CustomTorsionForce.h
@@ -159,7 +159,7 @@ public:
     * Set the default value of a global parameter.
     *
     * @param index          the index of the parameter for which to set the default value
-     * @param name           the default value of the parameter
+     * @param defaultValue   the default value of the parameter
     */
    void setGlobalParameterDefaultValue(int index, double defaultValue);
    /**
@@ -177,11 +177,11 @@ public:
     * Get the force field parameters for a torsion term.
     *
     * @param index              the index of the torsion for which to get parameters
-     * @param particle1     the index of the first particle connected by the torsion
+     * @param[out] particle1     the index of the first particle connected by the torsion
-     * @param particle2     the index of the second particle connected by the torsion
+     * @param[out] particle2     the index of the second particle connected by the torsion
-     * @param particle3     the index of the third particle connected by the torsion
+     * @param[out] particle3     the index of the third particle connected by the torsion
-     * @param particle4     the index of the fourth particle connected by the torsion
+     * @param[out] particle4     the index of the fourth particle connected by the torsion
-     * @param parameters    the list of parameters for the torsion
+     * @param[out] parameters    the list of parameters for the torsion
     */
    void getTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, std::vector<double>& parameters) const;
    /**

--- a/openmmapi/include/openmm/GBSAOBCForce.h
+++ b/openmmapi/include/openmm/GBSAOBCForce.h
@@ -100,9 +100,9 @@ public:
     * Get the force field parameters for a particle.
     *
     * @param index               the index of the particle for which to get parameters
-     * @param charge         the charge of the particle, measured in units of the proton charge
+     * @param[out] charge         the charge of the particle, measured in units of the proton charge
-     * @param radius         the GBSA radius of the particle, measured in nm
+     * @param[out] radius         the GBSA radius of the particle, measured in nm
-     * @param scalingFactor  the OBC scaling factor for the particle
+     * @param[out] scalingFactor  the OBC scaling factor for the particle
     */
    void getParticleParameters(int index, double& charge, double& radius, double& scalingFactor) const;
    /**

--- a/openmmapi/include/openmm/GBVIForce.h
+++ b/openmmapi/include/openmm/GBVIForce.h
@@ -110,9 +110,9 @@ public:
     * Get the force field parameters for a particle.
     *
     * @param index               the index of the particle for which to get parameters
-     * @param charge         the charge of the particle, measured in units of the proton charge
+     * @param[out] charge         the charge of the particle, measured in units of the proton charge
-     * @param radius         the GBSA radius of the particle, measured in nm
+     * @param[out] radius         the GBSA radius of the particle, measured in nm
-     * @param gamma          the gamma parameter
+     * @param[out] gamma          the gamma parameter
     */
    void getParticleParameters(int index, double& charge, double& radius, double& gamma) const;
    /**
@@ -138,9 +138,9 @@ public:
     * Get the parameters defining a bond
     *
     * @param      index     the index of the bond for which to get parameters
-     * @param particle1 the index of the first particle involved in the bond
+     * @param[out] particle1 the index of the first particle involved in the bond
-     * @param particle2 the index of the second particle involved in the bond
+     * @param[out] particle2 the index of the second particle involved in the bond
-     * @param distance  the distance between the two particles, measured in nm
+     * @param[out] distance  the distance between the two particles, measured in nm
     */
    void getBondParameters(int index, int& particle1, int& particle2, double& distance) const;
    /**

--- a/openmmapi/include/openmm/HarmonicAngleForce.h
+++ b/openmmapi/include/openmm/HarmonicAngleForce.h
@@ -74,11 +74,11 @@ public:
     * Get the force field parameters for an angle term.
     *
     * @param      index     the index of the angle for which to get parameters
-     * @param particle1 the index of the first particle forming the angle
+     * @param[out] particle1 the index of the first particle forming the angle
-     * @param particle2 the index of the second particle forming the angle
+     * @param[out] particle2 the index of the second particle forming the angle
-     * @param particle3 the index of the third particle forming the angle
+     * @param[out] particle3 the index of the third particle forming the angle
-     * @param angle     the equilibrium angle, measured in radians
+     * @param[out] angle     the equilibrium angle, measured in radians
-     * @param k         the harmonic force constant for the angle, measured in kJ/mol/radian^2
+     * @param[out] k         the harmonic force constant for the angle, measured in kJ/mol/radian^2
     */
    void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, double& angle, double& k) const;
    /**

--- a/openmmapi/include/openmm/HarmonicBondForce.h
+++ b/openmmapi/include/openmm/HarmonicBondForce.h
@@ -73,10 +73,10 @@ public:
     * Get the force field parameters for a bond term.
     *
     * @param      index     the index of the bond for which to get parameters
-     * @param particle1 the index of the first particle connected by the bond
+     * @param[out] particle1 the index of the first particle connected by the bond
-     * @param particle2 the index of the second particle connected by the bond
+     * @param[out] particle2 the index of the second particle connected by the bond
-     * @param length    the equilibrium length of the bond, measured in nm
+     * @param[out] length    the equilibrium length of the bond, measured in nm
-     * @param k         the harmonic force constant for the bond, measured in kJ/mol/nm^2
+     * @param[out] k         the harmonic force constant for the bond, measured in kJ/mol/nm^2
     */
    void getBondParameters(int index, int& particle1, int& particle2, double& length, double& k) const;
    /**

--- a/openmmapi/include/openmm/NonbondedForce.h
+++ b/openmmapi/include/openmm/NonbondedForce.h
@@ -201,10 +201,10 @@ public:
     * Get the parameters to use for PME calculations.  If alpha is 0 (the default), these parameters are
     * ignored and instead their values are chosen based on the Ewald error tolerance.
     *
-     * @param alpha   the separation parameter
+     * @param[out] alpha   the separation parameter
-     * @param nx      the number of grid points along the X axis
+     * @param[out] nx      the number of grid points along the X axis
-     * @param ny      the number of grid points along the Y axis
+     * @param[out] ny      the number of grid points along the Y axis
-     * @param nz      the number of grid points along the Z axis
+     * @param[out] nz      the number of grid points along the Z axis
     */
    void getPMEParameters(double& alpha, int& nx, int& ny, int& nz) const;
    /**
@@ -224,10 +224,10 @@ public:
     * See the manual for details.
     *
     * @param context      the Context for which to get the parameters
-     * @param alpha   the separation parameter
+     * @param[out] alpha   the separation parameter
-     * @param nx      the number of grid points along the X axis
+     * @param[out] nx      the number of grid points along the X axis
-     * @param ny      the number of grid points along the Y axis
+     * @param[out] ny      the number of grid points along the Y axis
-     * @param nz      the number of grid points along the Z axis
+     * @param[out] nz      the number of grid points along the Z axis
     */
    void getPMEParametersInContext(const Context& context, double& alpha, int& nx, int& ny, int& nz) const;
    /**
@@ -247,9 +247,9 @@ public:
     * Get the nonbonded force parameters for a particle.
     *
     * @param index          the index of the particle for which to get parameters
-     * @param charge    the charge of the particle, measured in units of the proton charge
+     * @param[out] charge    the charge of the particle, measured in units of the proton charge
-     * @param sigma     the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
+     * @param[out] sigma     the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
-     * @param epsilon   the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
+     * @param[out] epsilon   the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
     */
    void getParticleParameters(int index, double& charge, double& sigma, double& epsilon) const;
    /**
@@ -284,11 +284,11 @@ public:
     * Get the force field parameters for an interaction that should be calculated differently from others.
     *
     * @param index           the index of the interaction for which to get parameters
-     * @param particle1  the index of the first particle involved in the interaction
+     * @param[out] particle1  the index of the first particle involved in the interaction
-     * @param particle2  the index of the second particle involved in the interaction
+     * @param[out] particle2  the index of the second particle involved in the interaction
-     * @param chargeProd the scaled product of the atomic charges (i.e. the strength of the Coulomb interaction), measured in units of the proton charge squared
+     * @param[out] chargeProd the scaled product of the atomic charges (i.e. the strength of the Coulomb interaction), measured in units of the proton charge squared
-     * @param sigma      the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
+     * @param[out] sigma      the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
-     * @param epsilon    the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
+     * @param[out] epsilon    the epsilon parameter of the Lennard-Jones potential (corresponding to the well depth of the van der Waals interaction), measured in kJ/mol
     */
    void getExceptionParameters(int index, int& particle1, int& particle2, double& chargeProd, double& sigma, double& epsilon) const;
    /**

--- a/openmmapi/include/openmm/PeriodicTorsionForce.h
+++ b/openmmapi/include/openmm/PeriodicTorsionForce.h
@@ -76,13 +76,13 @@ public:
     * Get the force field parameters for a periodic torsion term.
     *
     * @param index             the index of the torsion for which to get parameters
-     * @param particle1    the index of the first particle forming the torsion
+     * @param[out] particle1    the index of the first particle forming the torsion
-     * @param particle2    the index of the second particle forming the torsion
+     * @param[out] particle2    the index of the second particle forming the torsion
-     * @param particle3    the index of the third particle forming the torsion
+     * @param[out] particle3    the index of the third particle forming the torsion
-     * @param particle4    the index of the fourth particle forming the torsion
+     * @param[out] particle4    the index of the fourth particle forming the torsion
-     * @param periodicity  the periodicity of the torsion
+     * @param[out] periodicity  the periodicity of the torsion
-     * @param phase        the phase offset of the torsion, measured in radians
+     * @param[out] phase        the phase offset of the torsion, measured in radians
-     * @param k            the force constant for the torsion
+     * @param[out] k            the force constant for the torsion
     */
    void getTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, int& periodicity, double& phase, double& k) const;
    /**

--- a/openmmapi/include/openmm/RBTorsionForce.h
+++ b/openmmapi/include/openmm/RBTorsionForce.h
@@ -79,16 +79,16 @@ public:
     * Get the force field parameters for a Ryckaert-Bellemans torsion term.
     *
     * @param index             the index of the torsion for which to get parameters
-     * @param particle1    the index of the first particle forming the torsion
+     * @param[out] particle1    the index of the first particle forming the torsion
-     * @param particle2    the index of the second particle forming the torsion
+     * @param[out] particle2    the index of the second particle forming the torsion
-     * @param particle3    the index of the third particle forming the torsion
+     * @param[out] particle3    the index of the third particle forming the torsion
-     * @param particle4    the index of the fourth particle forming the torsion
+     * @param[out] particle4    the index of the fourth particle forming the torsion
-     * @param c0           the coefficient of the constant term, measured in kJ/mol
+     * @param[out] c0           the coefficient of the constant term, measured in kJ/mol
-     * @param c1           the coefficient of the 1st order term, measured in kJ/mol
+     * @param[out] c1           the coefficient of the 1st order term, measured in kJ/mol
-     * @param c2           the coefficient of the 2nd order term, measured in kJ/mol
+     * @param[out] c2           the coefficient of the 2nd order term, measured in kJ/mol
-     * @param c3           the coefficient of the 3rd order term, measured in kJ/mol
+     * @param[out] c3           the coefficient of the 3rd order term, measured in kJ/mol
-     * @param c4           the coefficient of the 4th order term, measured in kJ/mol
+     * @param[out] c4           the coefficient of the 4th order term, measured in kJ/mol
-     * @param c5           the coefficient of the 5th order term, measured in kJ/mol
+     * @param[out] c5           the coefficient of the 5th order term, measured in kJ/mol
     */
    void getTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, double& c0, double& c1, double& c2, double& c3, double& c4, double& c5) const;
    /**

--- a/openmmapi/include/openmm/State.h
+++ b/openmmapi/include/openmm/State.h
@@ -95,9 +95,9 @@ public:
    /**
     * Get the vectors defining the axes of the periodic box (measured in nm).
     *
-     * @param a      on exit, this contains the vector defining the first edge of the periodic box
+     * @param[out] a    the vector defining the first edge of the periodic box
-     * @param b      on exit, this contains the vector defining the second edge of the periodic box
+     * @param[out] b    the vector defining the second edge of the periodic box
-     * @param c      on exit, this contains the vector defining the third edge of the periodic box
+     * @param[out] c    the vector defining the third edge of the periodic box
     */
    void getPeriodicBoxVectors(Vec3& a, Vec3& b, Vec3& c) const;
    /**