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.

openmmapi/include/openmm/System.h

@@ -153,9 +153,9 @@ public:
      * Get the parameters defining a distance constraint.
      *
      * @param index     the index of the constraint for which to get parameters
-     * @param particle1 the index of the first particle involved in the constraint
-     * @param particle2 the index of the second particle involved in the constraint
-     * @param distance  the required distance between the two particles, measured in nm
+     * @param[out] particle1 the index of the first particle involved in the constraint
+     * @param[out] particle2 the index of the second particle involved in the constraint
+     * @param[out] distance  the required distance between the two particles, measured in nm
      */
     void getConstraintParameters(int index, int& particle1, int& particle2, double& distance) const;
     /**
@@ -216,9 +216,9 @@ public:
      * created Context will have its box vectors set to these.  They will affect
      * any Force added to the System that uses periodic boundary conditions.
      *
-     * @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 getDefaultPeriodicBoxVectors(Vec3& a, Vec3& b, Vec3& c) const;
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaAngleForce.h

@@ -128,7 +128,7 @@ public:
      * @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 length        the equilibrium angle, measured in degrees
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @param quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
      * @return              the index of the angle that was added
      */
     int addAngle(int particle1, int particle2, int particle3, double length, double quadraticK);
@@ -137,11 +137,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 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 length        the equilibrium angle, measured in degrees
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @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] length        the equilibrium angle, measured in degrees
+     * @param[out] quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
      */
     void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, double& length, double& quadraticK) const;
 
@@ -153,7 +153,7 @@ public:
      * @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 length        the equilibrium angle, measured in degrees
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @param quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
      */
     void setAngleParameters(int index, int particle1, int particle2, int particle3, double length, double quadraticK);
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaBondForce.h

@@ -100,7 +100,7 @@ public:
      * @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 quadratic force constant for the bond
+     * @param quadraticK    the quadratic force constant for the bond
      * @return the index of the bond that was added
      */
 
@@ -110,10 +110,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 quadratic k   the quadratic force constant 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] length        the equilibrium length of the bond, measured in nm
+     * @param[out] quadraticK    the quadratic force constant for the bond
      */
 
     void getBondParameters(int index, int& particle1, int& particle2, double& length, double& quadraticK) const;
@@ -125,7 +125,7 @@ public:
      * @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 quadratic force constant for the bond
+     * @param quadraticK  the quadratic force constant for the bond
      */
     void setBondParameters(int index, int particle1, int particle2, double length, double quadraticK);
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaGeneralizedKirkwoodForce.h

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

plugins/amoeba/openmmapi/include/openmm/AmoebaInPlaneAngleForce.h

@@ -129,7 +129,7 @@ public:
      * @param particle3     the index of the third particle connected by the angle
      * @param particle4     the index of the fourth particle connected by the angle
      * @param length        the equilibrium angle, measured in radians
-     * @param quadratic k   the quadratic force constant for the angle measured in kJ/mol/radian^2
+     * @param quadraticK    the quadratic force constant for the angle measured in kJ/mol/radian^2
      * @return the index of the angle that was added
      */
     int addAngle(int particle1, int particle2, int particle3, int particle4, double length, 
@@ -139,12 +139,12 @@ 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 particle4     the index of the fourth particle connected by the angle
-     * @param length        the equilibrium angle, measured in radians
-     * @param quadratic k   the quadratic force constant for the angle measured in kJ/mol/radian^2
+     * @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] particle4     the index of the fourth particle connected by the angle
+     * @param[out] length        the equilibrium angle, measured in radians
+     * @param[out] quadraticK    the quadratic force constant for the angle measured in kJ/mol/radian^2
      */
     void getAngleParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, double& length,
                             double& quadraticK) const;
@@ -158,7 +158,7 @@ public:
      * @param particle3     the index of the third particle connected by the angle
      * @param particle4     the index of the fourth particle connected by the angle
      * @param length        the equilibrium angle, measured in radians
-     * @param quadratic k   the quadratic force constant for the angle, measured in kJ/mol/radian^2
+     * @param quadraticK    the quadratic force constant for the angle, measured in kJ/mol/radian^2
      */
     void setAngleParameters(int index, int particle1, int particle2, int particle3, int particle4, double length, double quadraticK);
     /**

plugins/amoeba/openmmapi/include/openmm/AmoebaMultipoleForce.h

@@ -148,7 +148,7 @@ public:
      * Set the Ewald alpha parameter.  If this is 0 (the default), a value is chosen automatically
      * based on the Ewald error tolerance.
      *
-     * @param Ewald alpha parameter
+     * @param aewald alpha parameter
      */
     void setAEwald(double aewald);
 
@@ -171,7 +171,7 @@ public:
      * Set the PME grid dimensions.  If Ewald alpha is 0 (the default), this is ignored and grid dimensions
      * are chosen automatically based on the Ewald error tolerance.
      *
-     * @param the PME grid dimensions
+     * @param gridDimension   the PME grid dimensions
      */
     void setPmeGridDimensions(const std::vector<int>& gridDimension);
 
@@ -182,10 +182,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;
 
@@ -212,16 +212,16 @@ public:
      * Get the multipole parameters for a particle.
      *
      * @param index                     the index of the atom for which to get parameters
-     * @param charge               the particle's charge
-     * @param molecularDipole      the particle's molecular dipole (vector of size 3)
-     * @param molecularQuadrupole  the particle's molecular quadrupole (vector of size 9)
-     * @param axisType             the particle's axis type
-     * @param multipoleAtomZ       index of first atom used in constructing lab<->molecular frames
-     * @param multipoleAtomX       index of second atom used in constructing lab<->molecular frames
-     * @param multipoleAtomY       index of second atom used in constructing lab<->molecular frames
-     * @param thole                Thole parameter
-     * @param dampingFactor        dampingFactor parameter
-     * @param polarity             polarity parameter
+     * @param[out] charge               the particle's charge
+     * @param[out] molecularDipole      the particle's molecular dipole (vector of size 3)
+     * @param[out] molecularQuadrupole  the particle's molecular quadrupole (vector of size 9)
+     * @param[out] axisType             the particle's axis type
+     * @param[out] multipoleAtomZ       index of first atom used in constructing lab<->molecular frames
+     * @param[out] multipoleAtomX       index of second atom used in constructing lab<->molecular frames
+     * @param[out] multipoleAtomY       index of second atom used in constructing lab<->molecular frames
+     * @param[out] thole                Thole parameter
+     * @param[out] dampingFactor        dampingFactor parameter
+     * @param[out] polarity             polarity parameter
      */
     void getMultipoleParameters(int index, double& charge, std::vector<double>& molecularDipole, std::vector<double>& molecularQuadrupole,
                                 int& axisType, int& multipoleAtomZ, int& multipoleAtomX, int& multipoleAtomY, double& thole, double& dampingFactor, double& polarity) const;
@@ -237,6 +237,8 @@ public:
      * @param multipoleAtomZ       index of first atom used in constructing lab<->molecular frames
      * @param multipoleAtomX       index of second atom used in constructing lab<->molecular frames
      * @param multipoleAtomY       index of second atom used in constructing lab<->molecular frames
+     * @param thole                thole parameter
+     * @param dampingFactor        damping factor parameter
      * @param polarity             polarity parameter
      */
     void setMultipoleParameters(int index, double charge, const std::vector<double>& molecularDipole, const std::vector<double>& molecularQuadrupole,
@@ -256,7 +258,7 @@ public:
      *
      * @param index                the index of the atom for which to set parameters
      * @param typeId               CovalentTypes type
-     * @param covalentAtoms        output vector of covalent atoms associated w/ the specfied CovalentType
+     * @param[out] covalentAtoms   output vector of covalent atoms associated w/ the specfied CovalentType
      */
     void getCovalentMap(int index, CovalentType typeId, std::vector<int>& covalentAtoms) const;
 
@@ -264,7 +266,7 @@ public:
      * Get the CovalentMap for an atom
      *
      * @param index                the index of the atom for which to set parameters
-     * @param covalentLists        output vector of covalent lists of atoms
+     * @param[out] covalentLists   output vector of covalent lists of atoms
      */
     void getCovalentMaps(int index, std::vector < std::vector<int> >& covalentLists) const;
 
@@ -278,7 +280,7 @@ public:
     /**
      * Set the max number of iterations to be used in calculating the mutual induced dipoles
      *
-     * @param max number of iterations
+     * @param inputMutualInducedMaxIterations   number of iterations
      */
     void setMutualInducedMaxIterations(int inputMutualInducedMaxIterations);
 
@@ -292,7 +294,7 @@ public:
     /**
      * Set the target epsilon to be used to test for convergence of iterative method used in calculating the mutual induced dipoles
      *
-     * @param target epsilon
+     * @param inputMutualInducedTargetEpsilon   target epsilon
      */
     void setMutualInducedTargetEpsilon(double inputMutualInducedTargetEpsilon);
 
@@ -319,7 +321,7 @@ public:
      * Get the induced dipole moments of all particles.
      *
      * @param context         the Context for which to get the induced dipoles
-     * @param dipoles    the induced dipole moment of particle i is stored into the i'th element
+     * @param[out] dipoles    the induced dipole moment of particle i is stored into the i'th element
      */
     void getInducedDipoles(Context& context, std::vector<Vec3>& dipoles);
 
@@ -328,7 +330,7 @@ public:
      *
      * @param inputGrid    input grid points over which the potential is to be evaluated
      * @param context      context
-     * @param outputElectrostaticPotential output potential
+     * @param[out] outputElectrostaticPotential output potential
      */
 
     void getElectrostaticPotential(const std::vector< Vec3 >& inputGrid,
@@ -344,7 +346,7 @@ public:
      * the quadrupole moment is still undefined and should be ignored.
      *
      * @param context      context
-     * @param outputMultipoleMoments (charge,
+     * @param[out] outputMultipoleMoments (charge,
                                            dipole_x, dipole_y, dipole_z,
                                            quadrupole_xx, quadrupole_xy, quadrupole_xz,
                                            quadrupole_yx, quadrupole_yy, quadrupole_yz,

plugins/amoeba/openmmapi/include/openmm/AmoebaOutOfPlaneBendForce.h

@@ -134,11 +134,11 @@ public:
      * Get the force field parameters for an out-of-plane bend term.
      * 
      * @param index              the index of the outOfPlaneBend for which to get parameters
-     * @param particle1     the index of the first particle connected by the outOfPlaneBend
-     * @param particle2     the index of the second particle connected by the outOfPlaneBend
-     * @param particle3     the index of the third particle connected by the outOfPlaneBend
-     * @param particle4     the index of the fourth particle connected by the outOfPlaneBend
-     * @param k             the force constant for the out-of-plane bend
+     * @param[out] particle1     the index of the first particle connected by the outOfPlaneBend
+     * @param[out] particle2     the index of the second particle connected by the outOfPlaneBend
+     * @param[out] particle3     the index of the third particle connected by the outOfPlaneBend
+     * @param[out] particle4     the index of the fourth particle connected by the outOfPlaneBend
+     * @param[out] k             the force constant for the out-of-plane bend
      */
     void getOutOfPlaneBendParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, double& k) const;
 

plugins/amoeba/openmmapi/include/openmm/AmoebaPiTorsionForce.h

@@ -80,13 +80,13 @@ 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 particle5     the index of the fifth particle connected by the torsion
-     * @param particle6     the index of the sixth particle connected by the torsion
-     * @param k             the force constant 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] particle5     the index of the fifth particle connected by the torsion
+     * @param[out] particle6     the index of the sixth particle connected by the torsion
+     * @param[out] k             the force constant for the torsion
      */
     void getPiTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, int& particle5, int& particle6, double& k) const;
 

plugins/amoeba/openmmapi/include/openmm/AmoebaStretchBendForce.h

@@ -82,14 +82,14 @@ public:
      * Get the force field parameters for a stretch-bend term.
      * 
      * @param index              the index of the stretch-bend for which to get parameters
-     * @param particle1     the index of the first particle connected by the stretch-bend
-     * @param particle2     the index of the second particle connected by the stretch-bend
-     * @param particle3     the index of the third particle connected by the stretch-bend
-     * @param lengthAB      the equilibrium length of the stretch-bend in bond ab [particle1, particle2], measured in nm
-     * @param lengthCB      the equilibrium length of the stretch-bend in bond cb [particle3, particle2], measured in nm
-     * @param angle         the equilibrium angle in radians
-     * @param k1            the force constant of the product of bond ab and angle a-b-c
-     * @param k2            the force constant of the product of bond bc and angle a-b-c
+     * @param[out] particle1     the index of the first particle connected by the stretch-bend
+     * @param[out] particle2     the index of the second particle connected by the stretch-bend
+     * @param[out] particle3     the index of the third particle connected by the stretch-bend
+     * @param[out] lengthAB      the equilibrium length of the stretch-bend in bond ab [particle1, particle2], measured in nm
+     * @param[out] lengthCB      the equilibrium length of the stretch-bend in bond cb [particle3, particle2], measured in nm
+     * @param[out] angle         the equilibrium angle in radians
+     * @param[out] k1            the force constant of the product of bond ab and angle a-b-c
+     * @param[out] k2            the force constant of the product of bond bc and angle a-b-c
      */
     void getStretchBendParameters(int index, int& particle1, int& particle2, int& particle3, double& lengthAB,
                                   double& lengthCB, double& angle, double& k1, double& k2) const;

plugins/amoeba/openmmapi/include/openmm/AmoebaTorsionTorsionForce.h

@@ -90,13 +90,13 @@ public:
      * Get the force field parameters for a torsion-torsion term.
      *
      * @param index                          the index of the torsion-torsion for which to get parameters
-     * @param particle1                 the index of the first particle connected by the torsion-torsion
-     * @param particle2                 the index of the second particle connected by the torsion-torsion
-     * @param particle3                 the index of the third particle connected by the torsion-torsion
-     * @param particle4                 the index of the fourth particle connected by the torsion-torsion
-     * @param particle5                 the index of the fifth particle connected by the torsion-torsion
-     * @param chiralCheckAtomIndex      the index of the particle connected to particle3, but not particle2 or particle4 to be used in chirality check
-     * @param gridIndex                 the grid index
+     * @param[out] particle1                 the index of the first particle connected by the torsion-torsion
+     * @param[out] particle2                 the index of the second particle connected by the torsion-torsion
+     * @param[out] particle3                 the index of the third particle connected by the torsion-torsion
+     * @param[out] particle4                 the index of the fourth particle connected by the torsion-torsion
+     * @param[out] particle5                 the index of the fifth particle connected by the torsion-torsion
+     * @param[out] chiralCheckAtomIndex      the index of the particle connected to particle3, but not particle2 or particle4 to be used in chirality check
+     * @param[out] gridIndex                 the grid index
      */
     void getTorsionTorsionParameters(int index, int& particle1, int& particle2, int& particle3, int& particle4, int& particle5, int& chiralCheckAtomIndex, int& gridIndex) const;
 
@@ -117,7 +117,7 @@ public:
     /**
      * Get the torsion-torsion grid at the specified index
      *
-     * @param gridIndex     the grid index
+     * @param  index        the grid index
      * @return grid         return grid reference
      */
     const std::vector<std::vector<std::vector<double> > >& getTorsionTorsionGrid(int index) const;

plugins/amoeba/openmmapi/include/openmm/AmoebaVdwForce.h

@@ -98,10 +98,10 @@ public:
      * Get the force field parameters for a vdw particle.
      * 
      * @param particleIndex        the particle index
-     * @param parentIndex     the index of the parent particle
-     * @param sigma           vdw sigma
-     * @param epsilon         vdw epsilon
-     * @param reductionFactor the fraction of the distance along the line from the parent particle to this particle
+     * @param[out] parentIndex     the index of the parent particle
+     * @param[out] sigma           vdw sigma
+     * @param[out] epsilon         vdw epsilon
+     * @param[out] reductionFactor the fraction of the distance along the line from the parent particle to this particle
      *                             at which the interaction site should be placed
      */
     void getParticleParameters(int particleIndex, int& parentIndex, double& sigma, double& epsilon, double& reductionFactor) const;
@@ -179,7 +179,7 @@ public:
      * Get exclusions for specified particle
      * 
      * @param particleIndex    particle index
-     * @param exclusions vector of exclusions
+     * @param[out] exclusions  vector of exclusions
      */
     void getParticleExclusions(int particleIndex, std::vector<int>& exclusions) const;
 

plugins/amoeba/openmmapi/include/openmm/AmoebaWcaDispersionForce.h

@@ -76,8 +76,8 @@ public:
      * Get the force field parameters for a WCA dispersion particle.
      * 
      * @param particleIndex        the particle index
-     * @param radius          radius
-     * @param epsilon         epsilon 
+     * @param[out] radius          radius
+     * @param[out] epsilon         epsilon 
      */
     void getParticleParameters(int particleIndex, double& radius, double& epsilon) const;
 

plugins/drude/openmmapi/include/openmm/DrudeForce.h

@@ -92,18 +92,18 @@ public:
      * Get the parameters for a Drude particle.
      *
      * @param index                the index of the Drude particle for which to get parameters
-     * @param particle        the index within the System of the Drude particle
-     * @param particle1       the index within the System of the particle to which the Drude particle is attached
-     * @param particle2       the index within the System of the second particle used for defining anisotropic polarizability.
+     * @param[out] particle        the index within the System of the Drude particle
+     * @param[out] particle1       the index within the System of the particle to which the Drude particle is attached
+     * @param[out] particle2       the index within the System of the second particle used for defining anisotropic polarizability.
      *                             This may be set to -1, in which case aniso12 will be ignored.
-     * @param particle3       the index within the System of the third particle used for defining anisotropic polarizability.
+     * @param[out] particle3       the index within the System of the third particle used for defining anisotropic polarizability.
      *                             This may be set to -1, in which case aniso34 will be ignored.
-     * @param particle4       the index within the System of the fourth particle used for defining anisotropic polarizability.
+     * @param[out] particle4       the index within the System of the fourth particle used for defining anisotropic polarizability.
      *                             This may be set to -1, in which case aniso34 will be ignored.
-     * @param charge          The charge on the Drude particle
-     * @param polarizability  The isotropic polarizability
-     * @param aniso12         The scale factor for the polarizability along the direction defined by particle1 and particle2
-     * @param aniso34         The scale factor for the polarizability along the direction defined by particle3 and particle4
+     * @param[out] charge          The charge on the Drude particle
+     * @param[out] polarizability  The isotropic polarizability
+     * @param[out] aniso12         The scale factor for the polarizability along the direction defined by particle1 and particle2
+     * @param[out] aniso34         The scale factor for the polarizability along the direction defined by particle3 and particle4
      */
     void getParticleParameters(int index, int& particle, int& particle1, int& particle2, int& particle3, int& particle4, double& charge, double& polarizability, double& aniso12, double& aniso34) const;
     /**
@@ -136,10 +136,9 @@ public:
     /**
      * Get the force field parameters for screened pair.
      *
-     * @param index      the index of the pair for which to get parameters
-     * @param particle1  the index within this Force of the first particle involved in the interaction
-     * @param particle2  the index within this Force of the second particle involved in the interaction
-     * @param thole      the Thole screening factor
+     * @param[out] particle1  the index within this Force of the first particle involved in the interaction
+     * @param[out] particle2  the index within this Force of the second particle involved in the interaction
+     * @param[out] thole      the Thole screening factor
      */
     void getScreenedPairParameters(int index, int& particle1, int& particle2, double& thole) const;
     /**

serialization/include/openmm/serialization/SerializationNode.h

@@ -105,7 +105,7 @@ public:
     /**
      * Determine whether this node has a property with a particular node.
      *
-     * @param the name of the property to check for
+     * @param name  the name of the property to check for
      */
     bool hasProperty(const std::string& name) const;
     /**

wrappers/python/filterPythonFiles.py

 from __future__ import print_function
+from numpydoc.docscrape import NumpyDocString
 import sys
+import textwrap
+
 
 # Doxygen does a bad job of generating documentation based on docstrings.  This script is run as a filter
 # on each file, and converts the docstrings into Doxygen style comments so we get better documentation.
@@ -15,10 +18,10 @@ while True:
         split = stripped.split()
         if split[0] == 'class' and split[1][0].islower():
             # Classes that start with a lowercase letter were defined by SWIG.  We want to hide them.
-            print("%s## @private" % prefix)
+            print("%s## @private" % prefix, end='')
         if split[1][0] == '_' and split[1][1] != '_':
             # Names starting with a single _ are assumed to be private.
-            print("%s## @private" % prefix)
+            print("%s## @private" % prefix, end='')
 
         # We're at the start of a class or function definition.  Find all lines that contain the declaration.
 
@@ -29,32 +32,37 @@ while True:
 
         # Now look for a docstring.
 
-        docstrings = []
+        docstringlines = []
         line = input.readline()
         stripped = line.lstrip()
-        if stripped.startswith('"""'):
+        if stripped.startswith('"""') or stripped.startswith("'''"):
             line = stripped[3:]
             readingParameters = False
+            if line.find('"""') != -1 or line.find(("'''")) != -1:
+                docstringlines.append(line.rstrip()[:-3])
+            else:
                 while line.find('"""') == -1:
-                docstrings.append(line)
+                    docstringlines.append(line)
                     line = input.readline()
-                if line.strip() == 'Parameters:':
-                    readingParameters = True
-                    line = input.readline()
-                stripped = line.lstrip()
-                if readingParameters and stripped.startswith('- '):
-                    line = "@param %s" % stripped[2:]
-                elif stripped.startswith('Returns:'):
-                    line = "@return %s" % stripped[8:]
-            line = line[:line.find('"""')]
-            docstrings.append(line)            
+        docstring = NumpyDocString(''.join(docstringlines))
 
         # Print out the docstring in Doxygen syntax, followed by the declaration.
+        sep = '\n{prefix}##\n{prefix}## '.format(prefix=prefix)
+        for line in textwrap.wrap(' '.join(docstring['Summary'])):
+            print('{prefix}## {line}'.format(prefix=prefix, line=line))
+        if len(docstring['Extended Summary']) > 0:
+            print('{prefix}##'.format(prefix=prefix))
+            print('{prefix}## {ext_summary}'.format(prefix=prefix, ext_summary=sep.join(docstring['Extended Summary'])))
+        print('{prefix}##'.format(prefix=prefix))
+        for name, type, descr in docstring['Parameters']:
+            print('{prefix}## @param {name} ({type}) {descr}'.format(prefix=prefix, type=type, name=name, descr=''.join(descr)))
+        for name, type, descr in docstring['Returns']:
+            if type == '':
+                type = name
+            print('{prefix}## @return ({type}) {descr}'.format(prefix=prefix, type=type, name=name, descr=''.join(descr)))
 
-        for s in docstrings:
-            print("%s##%s" % (prefix, s.strip()))
         print(declaration)
-        if len(docstrings) == 0:
-            print(line)
+        if len(docstringlines) == 0:
+            print(line, end='')
     else:
-        print(line)
\ No newline at end of file
+        print(line, end='')

wrappers/python/simtk/openmm/app/amberinpcrdfile.py

@@ -60,12 +60,17 @@ class AmberInpcrdFile(object):
     def __init__(self, file, loadVelocities=None, loadBoxVectors=None):
         """Load an inpcrd file.
 
-        An inpcrd file contains atom positions and, optionally, velocities and periodic box dimensions.
-
-        Parameters:
-         - file (string) the name of the file to load
-         - loadVelocities (boolean=None) deprecated. Velocities are loaded automatically if present
-         - loadBoxVectors (boolean=None) deprecated. Box vectors are loaded automatically if present
+        An inpcrd file contains atom positions and, optionally, velocities and
+        periodic box dimensions.
+
+        Parameters
+        ----------
+        file : str
+             The name of the file to load
+        loadVelocities : bool
+             Deprecated. Velocities are loaded automatically if present
+        loadBoxVectors : bool
+            Deprecated. Box vectors are loaded automatically if present
         """
         self.file = file
         if loadVelocities is not None or loadBoxVectors is not None:
@@ -84,8 +89,11 @@ class AmberInpcrdFile(object):
     def getPositions(self, asNumpy=False):
         """Get the atomic positions.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
+        Parameters
+        ----------
+        asNumpy : bool=False
+            if true, the values are returned as a numpy array instead of a list
+            of Vec3s
         """
         if asNumpy:
             if self._numpyPositions is None:
@@ -97,8 +105,10 @@ class AmberInpcrdFile(object):
     def getVelocities(self, asNumpy=False):
         """Get the atomic velocities.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the vectors are returned as numpy arrays instead of Vec3s
+        Parameters
+        ----------
+        asNumpy : bool=False
+            if true, the vectors are returned as numpy arrays instead of Vec3s
         """
         if self.velocities is None:
             raise AttributeError('velocities not found in %s' % self.file)
@@ -112,8 +122,11 @@ class AmberInpcrdFile(object):
     def getBoxVectors(self, asNumpy=False):
         """Get the periodic box vectors.
 
-        Parameters:
-         - asNumpy (boolean=False) if true, the values are returned as a numpy array instead of a list of Vec3s
+        Parameters
+        ----------
+        asNumpy : bool=False
+            if true, the values are returned as a numpy array instead of a list
+            of Vec3s
         """
         if self.boxVectors is None:
             raise AttributeError('Box information not found in %s' % self.file)

wrappers/python/simtk/openmm/app/amberprmtopfile.py

@@ -151,29 +151,51 @@ class AmberPrmtopFile(object):
                      implicitSolventKappa=None, temperature=298.15*unit.kelvin,
                      soluteDielectric=1.0, solventDielectric=78.5,
                      removeCMMotion=True, hydrogenMass=None, ewaldErrorTolerance=0.0005):
-        """Construct an OpenMM System representing the topology described by this prmtop file.
+        """Construct an OpenMM System representing the topology described by this
+        prmtop file.
 
-        Parameters:
-         - nonbondedMethod (object=NoCutoff) The method to use for nonbonded interactions.  Allowed values are
+        Parameters
+        ----------
+        nonbondedMethod : object=NoCutoff
+            The method to use for nonbonded interactions.  Allowed values are
             NoCutoff, CutoffNonPeriodic, CutoffPeriodic, Ewald, or PME.
-         - nonbondedCutoff (distance=1*nanometer) The cutoff distance to use for nonbonded interactions
-         - constraints (object=None) Specifies which bonds angles should be implemented with constraints.
+        nonbondedCutoff : distance=1*nanometer
+            The cutoff distance to use for nonbonded interactions
+        constraints : object=None
+            Specifies which bonds angles should be implemented with constraints.
             Allowed values are None, HBonds, AllBonds, or HAngles.
-         - rigidWater (boolean=True) If true, water molecules will be fully rigid regardless of the value passed for the constraints argument
-         - implicitSolvent (object=None) If not None, the implicit solvent model to use.  Allowed values are HCT, OBC1, OBC2, GBn, or GBn2.
-         - implicitSolventSaltConc (float=0.0*unit.moles/unit.liter) The salt concentration for GB 
-                    calculations (modelled as a debye screening parameter). It is converted to the debye length (kappa)
+        rigidWater : boolean=True
+            If true, water molecules will be fully rigid regardless of the value
+            passed for the constraints argument
+        implicitSolvent : object=None
+            If not None, the implicit solvent model to use.  Allowed values are
+            HCT, OBC1, OBC2, GBn, or GBn2.
+        implicitSolventSaltConc : float=0.0*unit.moles/unit.liter
+            The salt concentration for GB calculations (modelled as a debye
+            screening parameter). It is converted to the debye length (kappa)
             using the provided temperature and solventDielectric
-         - temperature (float=300*kelvin) Temperature of the system. Only used to compute the Debye length from
-                    implicitSolventSoltConc
-         - implicitSolventKappa (float units of 1/length) If this value is set, implicitSolventSaltConc will be ignored.
-         - soluteDielectric (float=1.0) The solute dielectric constant to use in the implicit solvent model.
-         - solventDielectric (float=78.5) The solvent dielectric constant to use in the implicit solvent model.
-         - removeCMMotion (boolean=True) If true, a CMMotionRemover will be added to the System
-         - hydrogenMass (mass=None) The mass to use for hydrogen atoms bound to heavy atoms.  Any mass added to a hydrogen is
-           subtracted from the heavy atom to keep their total mass the same.
-         - ewaldErrorTolerance (float=0.0005) The error tolerance to use if nonbondedMethod is Ewald or PME.
-        Returns: the newly created System
+        temperature : float=300*kelvin
+            Temperature of the system. Only used to compute the Debye length
+            from implicitSolventSoltConc
+        implicitSolventKappa : float units of 1/length
+            If this value is set, implicitSolventSaltConc will be ignored.
+        soluteDielectric : float=1.0
+            The solute dielectric constant to use in the implicit solvent model.
+        solventDielectric : float=78.5
+            The solvent dielectric constant to use in the implicit solvent
+            model.
+        removeCMMotion : boolean=True
+            If true, a CMMotionRemover will be added to the System
+        hydrogenMass : mass=None
+            The mass to use for hydrogen atoms bound to heavy atoms.  Any mass
+            added to a hydrogen is subtracted from the heavy atom to keep their
+            total mass the same.
+        ewaldErrorTolerance : float=0.0005
+            The error tolerance to use if nonbondedMethod is Ewald or PME.
+
+        Returns
+        -------
+            the newly created System
         """
         if self._prmtop.chamber:
             raise ValueError("CHAMBER-style topology file detected. CHAMBER "

wrappers/python/simtk/openmm/app/charmmcrdfiles.py

@@ -49,12 +49,17 @@ class CharmmCrdFile(object):
     Reads and parses a CHARMM coordinate file (.crd) into its components,
     namely the coordinates, CHARMM atom types, resid, resname, etc.
 
-    Main attributes:
-        - natom (int) : Number of atoms in the system
-        - resname (list) : Names of all residues
-        - positions (list) : All cartesian coordinates [x1, y1, z1, x2, ...]
-
-    Example:
+    Attributes
+    ----------
+    natom : int
+        Number of atoms in the system
+    resname : list
+        Names of all residues
+    positions : list
+        All cartesian coordinates [x1, y1, z1, x2, ...]
+
+    Examples
+    --------
     >>> chm = CharmmCrdFile('testfiles/1tnm.crd')
     >>> print '%d atoms; %d coords' % (chm.natom, len(chm.positions))
     1414 atoms; 1414 coords
@@ -131,14 +136,21 @@ class CharmmRstFile(object):
     Reads and parses data, velocities and coordinates from a CHARMM restart
     file (.rst) of file name 'fname' into class attributes
 
-    Main attributes:
-        - natom (int) : Number of atoms in the system
-        - resname (list) : Names of all residues
-        - positions (list) : All cartesian coordinates [x1, y1, z1, x2, ...]
-        - positionsold (list) : Old cartesian coordinates
-        - velocities (list) : List of all cartesian velocities
-
-    Example:
+    Attributes
+    ----------
+    natom : int
+        Number of atoms in the system
+    resname : list
+        Names of all residues
+    positions : list
+        All cartesian coordinates [x1, y1, z1, x2, ...]
+    positionsold : list
+        Old cartesian coordinates
+    velocities : list
+        List of all cartesian velocities
+
+    Examples
+    --------
     >>> chm = CharmmRstFile('testfiles/sample-charmm.rst')
     >>> print chm.header[0]
     REST    37     1

wrappers/python/simtk/openmm/app/charmmparameterset.py

@@ -51,18 +51,19 @@ class CharmmParameterSet(object):
     the information found in the MASS section of the CHARMM topology file
     (TOP/RTF) and all of the information in the parameter files (PAR)
 
-    Parameters:
-        - filenames : List of topology, parameter, and stream files to load into
-          the parameter set. The following file type suffixes are recognized.
-          Unrecognized file types raise a TypeError
-            .rtf, .top -- Residue topology file
-            .par, .prm -- Parameter file
-            .str -- Stream file
-            .inp -- If "par" is in the file name, it is a parameter file. If
+    Parameters
+    ----------
+    filenames : List of topology, parameter, and stream files to load into the parameter set.
+        The following file type suffixes are recognized. Unrecognized file types raise a TypeError
+          * .rtf, .top -- Residue topology file
+          * .par, .prm -- Parameter file
+          * .str -- Stream file
+          * .inp -- If "par" is in the file name, it is a parameter file. If
                     "top" is in the file name, it is a topology file. Otherwise,
                     raise TypeError
 
-    Attributes:
+    Attributes
+    ----------
     All type lists are dictionaries whose keys are tuples (with however
     many elements are needed to define that type of parameter). The types
     that can be in any order are SORTED.
@@ -85,7 +86,8 @@ class CharmmParameterSet(object):
     when only the integer or string is available the other dictionaries are
     helpful
 
-    Example:
+    Examples
+    --------
     >>> params = CharmmParameterSet('charmm22.top', 'charmm22.par', 'file.str')
     """
 
@@ -150,18 +152,25 @@ class CharmmParameterSet(object):
         Instantiates a CharmmParameterSet from a Topology file and a Parameter
         file (or just a Parameter file if it has all information)
 
-        Parameters:
-            - tfile (str) : Name of the Topology (RTF/TOP) file
-            - pfile (str) : Name of the Parameter (PAR) file
-            - sfiles (list of str) : List or tuple of stream (STR) file names.
-            - permissive (bool) : Accept non-bonbded parameters for undefined 
-                                  atom types (default False)
-
-        Returns:
+        Parameters
+        -----------
+        tfile : str
+            Name of the Topology (RTF/TOP) file
+        pfile : str
+            Name of the Parameter (PAR) file
+        sfiles : list of str
+            List or tuple of stream (STR) file names.
+        permissive : bool=False
+            Accept non-bonbded parameters for undefined atom types
+
+        Returns
+        -------
+        CharmmParameterSet
             New CharmmParameterSet populated with the parameters found in the
             provided files.
 
-        Notes:
+        Notes
+        -----
         The RTF file is read first (if provided), followed by the PAR file,
         followed by the list of stream files (in the order they are
         provided). Parameters in each stream file will overwrite those that
@@ -183,21 +192,24 @@ class CharmmParameterSet(object):
         return inst
 
     def readParameterFile(self, pfile, permissive=False):
-        """
-        Reads all of the parameters from a parameter file. Versions 36 and
-        later of the CHARMM force field files have an ATOMS section defining
-        all of the atom types.  Older versions need to load this information
-        from the RTF/TOP files.
-
-        Parameters:
-            - pfile (str) : Name of the CHARMM PARameter file to read
-            - permissive (bool) : Accept non-bonbded parameters for undefined 
-                                  atom types (default False)
-
-        Notes: The atom types must all be loaded by the end of this routine.
-        Either supply a PAR file with atom definitions in them or read in a
-        RTF/TOP file first. Failure to do so will result in a raised
-        RuntimeError.
+        """Reads all of the parameters from a parameter file. Versions 36 and later
+        of the CHARMM force field files have an ATOMS section defining all of
+        the atom types.  Older versions need to load this information from the
+        RTF/TOP files.
+
+        Parameters
+        ----------
+        pfile : str
+            Name of the CHARMM PARameter file to read
+        permissive : bool
+            Accept non-bonbded parameters for undefined atom types (default:
+            False).
+
+        Notes
+        -----
+        The atom types must all be loaded by the end of this routine. Either
+        supply a PAR file with atom definitions in them or read in a RTF/TOP
+        file first. Failure to do so will result in a raised RuntimeError.
         """
         conv = CharmmParameterSet._convert
         if isinstance(pfile, str):
@@ -518,14 +530,17 @@ class CharmmParameterSet(object):
         if own_handle: f.close()
 
     def readTopologyFile(self, tfile):
-        """
-        Reads _only_ the atom type definitions from a topology file. This is
+        """Reads _only_ the atom type definitions from a topology file. This is
         unnecessary for versions 36 and later of the CHARMM force field.
 
-        Parameters:
-            - tfile (str) : Name of the CHARMM TOPology file to read
+        Parameters
+        ----------
+        tfile : str
+            : Name of the CHARMM TOPology file to read
 
-        Note: The CHARMM TOPology file is also called a Residue Topology File
+        Notes
+        -----
+        The CHARMM TOPology file is also called a Residue Topology File
         """
         conv = CharmmParameterSet._convert
         if isinstance(tfile, str):
@@ -564,12 +579,13 @@ class CharmmParameterSet(object):
         if own_handle: f.close()
 
     def readStreamFile(self, sfile):
-        """
-        Reads RTF and PAR sections from a stream file and dispatches the
+        """Reads RTF and PAR sections from a stream file and dispatches the
         sections to readTopologyFile or readParameterFile
 
-        Parameters:
-            - sfile (str or CharmmStreamFile) : Stream file to parse
+        Parameters
+        ----------
+        sfile : str or CharmmStreamFile
+            Stream file to parse
         """
         if isinstance(sfile, CharmmStreamFile):
             f = sfile
@@ -594,15 +610,13 @@ class CharmmParameterSet(object):
         bond, angle, dihedral, improper, or cmap type will pair with EVERY key
         in the type mapping dictionaries that points to the equivalent type
 
-        Returns:
-            - Returns the instance that is being condensed.
-
-        Notes:
-            The return value allows you to condense the types at construction
-            time.
-
-        Example:
+        Example
+        -------
         >>> params = CharmmParameterSet('charmm.prm').condense()
+
+        Returns
+        -------
+        self
         """
         # First scan through all of the bond types
         self._condense_types(self.bond_types)
@@ -631,8 +645,10 @@ class CharmmParameterSet(object):
         """
         Loops through the given dict and condenses all types.
 
-        Parameter:
-            - typedict : Type dictionary to condense
+        Parameters
+        ----------
+        typedict
+            Type dictionary to condense
         """
         keylist = list(typedict.keys())
         for i in range(len(keylist) - 1):