Merge pull request #1228 from rmcgibbo/docstrings

Better docstrings

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 energy  the energy values for the map.  This must be of length size*size.
+     * @param[out] size    the size of the map along each dimension
+     * @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 a1    the index of the first particle forming the first torsion
-     * @param a2    the index of the second particle forming the first torsion
-     * @param a3    the index of the third particle forming the first torsion
-     * @param a4    the index of the fourth particle forming the first torsion
-     * @param b1    the index of the first particle forming the second torsion
-     * @param b2    the index of the second particle forming the second torsion
-     * @param 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] map   the index of the map to use for this term
+     * @param[out] a1    the index of the first particle forming the first torsion
+     * @param[out] a2    the index of the second particle forming the first torsion
+     * @param[out] a3    the index of the third particle forming the first torsion
+     * @param[out] a4    the index of the fourth particle forming the first torsion
+     * @param[out] b1    the index of the first particle forming the second torsion
+     * @param[out] b2    the index of the second particle forming the second torsion
+     * @param[out] b3    the index of the third 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;
     /**

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 particle2     the index of the second particle connected by the angle
-     * @param particle3     the index of the third particle connected by the angle
-     * @param parameters    the list of parameters for the angle
+     * @param[out] particle1     the index of the first particle connected by the angle
+     * @param[out] particle2     the index of the second particle connected by the angle
+     * @param[out] particle3     the index of the third particle connected by 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;
     /**

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 particle2     the index of the second particle connected by the bond
-     * @param parameters    the list of parameters for the bond
+     * @param[out] particle1     the index of the first particle connected by the bond
+     * @param[out] particle2     the index of the second particle connected by 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;
     /**

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 weights     the weight used for each particle when computing the center position.
+     * @param[out] particles   the indices of the particles in the group
+     * @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 parameters  the list of per-bond parameter values for the bond
+     * @param[out] groups      the indices of the groups in 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;
     /**

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 parameters  the list of per-bond parameter values for the bond
+     * @param[out] particles   the indices of the particles in 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;
     /**

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 parameters    the list of parameters for the force field term
+     * @param[out] particle      the index of the particle this term is applied to
+     * @param[out] parameters    the list of parameters for the force field term
      */
     void getParticleParameters(int index, int& particle, std::vector<double>& parameters) const;
     /**

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 expression  an algebraic expression to evaluate when calculating the computed value.  If the
+     * @param[out] name        the name of the value
+     * @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 particle2  the index of the second particle in the pair
+     * @param[out] particle1  the index of the first 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;
     /**

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 d2          the index of the second particle for this donor group.  If the group only
+     * @param[out] d1          the index of the first particle for this donor group
+     * @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 a2          the index of the second particle for this acceptor group.  If the group only
+     * @param[out] a1          the index of the first particle for this acceptor group
+     * @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 particle2  the index of the acceptor
+     * @param[out] particle1  the index of the donor
+     * @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 particle2  the index of the acceptor
+     * @param donor      the index of the donor
+     * @param acceptor   the index of the acceptor
      */
     void setExclusionParticles(int index, int donor, int acceptor);
     /**

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 variable   on exit, the variable into which this step stores its result.  If this
-     *                   step does not store a result in a variable, this will be an
-     *                   empty string.
-     * @param expression on exit, the expression this step evaluates.  If this step does not
-     *                   evaluate an expression, this will be an empty string.
+     * @param[out] type        the type of computation this step performs
+     * @param[out] variable    the variable into which this step stores its
+     *                         result.  If this step does not store a result in
+     *                         a variable, this will be an empty string.
+     * @param[out] expression  the expression this step evaluates.  If
+     *                         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;
     /**

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 type        the type of the specified particle
+     * @param[out] parameters  the list of parameters for 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 particle2  the index of the second particle in the pair
+     * @param[out] particle1  the index of the first 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;
     /**

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 particle2  the index of the second particle in the pair
+     * @param[out] particle1  the index of the first 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 set2    the second set of particles forming the interaction group
+     * @param[out] set1    the first 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;
     /**

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 particle2     the index of the second particle connected by the torsion
-     * @param particle3     the index of the third particle connected by the torsion
-     * @param particle4     the index of the fourth particle connected by the torsion
-     * @param parameters    the list of parameters for the torsion
+     * @param[out] particle1     the index of the first particle connected by the torsion
+     * @param[out] particle2     the index of the second particle connected by the torsion
+     * @param[out] particle3     the index of the third particle connected by the torsion
+     * @param[out] particle4     the index of the fourth particle connected by 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;
     /**

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 radius         the GBSA radius of the particle, measured in nm
-     * @param scalingFactor  the OBC scaling factor for the particle
+     * @param[out] charge         the charge of the particle, measured in units of the proton charge
+     * @param[out] radius         the GBSA radius of the particle, measured in nm
+     * @param[out] scalingFactor  the OBC scaling factor for the particle
      */
     void getParticleParameters(int index, double& charge, double& radius, double& scalingFactor) const;
     /**

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 radius         the GBSA radius of the particle, measured in nm
-     * @param gamma          the gamma parameter
+     * @param[out] charge         the charge of the particle, measured in units of the proton charge
+     * @param[out] radius         the GBSA radius of the particle, measured in nm
+     * @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 particle2 the index of the second particle involved in the bond
-     * @param distance  the distance between the two particles, measured in nm
+     * @param[out] particle1 the index of the first particle involved in the bond
+     * @param[out] particle2 the index of the second particle involved in the bond
+     * @param[out] distance  the distance between the two particles, measured in nm
      */
     void getBondParameters(int index, int& particle1, int& particle2, double& distance) const;
     /**

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 particle2 the index of the second particle forming the angle
-     * @param particle3 the index of the third particle forming the angle
-     * @param angle     the equilibrium angle, measured in radians
-     * @param k         the harmonic force constant for the angle, measured in kJ/mol/radian^2
+     * @param[out] particle1 the index of the first particle forming the angle
+     * @param[out] particle2 the index of the second particle forming the angle
+     * @param[out] particle3 the index of the third particle forming the angle
+     * @param[out] angle     the equilibrium angle, measured in radians
+     * @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;
     /**

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 particle2 the index of the second particle connected by the bond
-     * @param 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] particle1 the index of the first particle connected by the bond
+     * @param[out] particle2 the index of the second particle connected by the bond
+     * @param[out] length    the equilibrium length of the bond, measured in nm
+     * @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;
     /**

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 nx      the number of grid points along the X axis
-     * @param ny      the number of grid points along the Y axis
-     * @param nz      the number of grid points along the Z axis
+     * @param[out] alpha   the separation parameter
+     * @param[out] nx      the number of grid points along the X axis
+     * @param[out] ny      the number of grid points along the Y 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 nx      the number of grid points along the X axis
-     * @param ny      the number of grid points along the Y axis
-     * @param nz      the number of grid points along the Z axis
+     * @param[out] alpha   the separation parameter
+     * @param[out] nx      the number of grid points along the X axis
+     * @param[out] ny      the number of grid points along the Y 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 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] charge    the charge of the particle, measured in units of the proton charge
+     * @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[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 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 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] particle1  the index of the first particle involved in the interaction
+     * @param[out] particle2  the index of the second particle involved in the interaction
+     * @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[out] sigma      the sigma parameter of the Lennard-Jones potential (corresponding to the van der Waals radius of the particle), measured in nm
+     * @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;
     /**

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 particle2    the index of the second particle forming the torsion
-     * @param particle3    the index of the third particle forming the torsion
-     * @param particle4    the index of the fourth particle forming the torsion
-     * @param periodicity  the periodicity of the torsion
-     * @param phase        the phase offset of the torsion, measured in radians
-     * @param k            the force constant for the torsion
+     * @param[out] particle1    the index of the first particle forming the torsion
+     * @param[out] particle2    the index of the second particle forming the torsion
+     * @param[out] particle3    the index of the third particle forming the torsion
+     * @param[out] particle4    the index of the fourth particle forming the torsion
+     * @param[out] periodicity  the periodicity of the torsion
+     * @param[out] phase        the phase offset of the torsion, measured in radians
+     * @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;
     /**

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 particle2    the index of the second particle forming the torsion
-     * @param particle3    the index of the third particle forming the torsion
-     * @param particle4    the index of the fourth particle forming the torsion
-     * @param 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 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 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] particle1    the index of the first particle forming the torsion
+     * @param[out] particle2    the index of the second particle forming the torsion
+     * @param[out] particle3    the index of the third particle forming the torsion
+     * @param[out] particle4    the index of the fourth particle forming the torsion
+     * @param[out] c0           the coefficient of the constant term, measured in kJ/mol
+     * @param[out] c1           the coefficient of the 1st order term, measured in kJ/mol
+     * @param[out] c2           the coefficient of the 2nd order term, measured in kJ/mol
+     * @param[out] c3           the coefficient of the 3rd order term, measured in kJ/mol
+     * @param[out] c4           the coefficient of the 4th 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;
     /**

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 b      on exit, this contains 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] a    the vector defining the first edge of the periodic box
+     * @param[out] b    the vector defining the second 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;
     /**