subjected to rigid-body transformations. The rmsd calculation does
not perform structural best-fit alignment.
1) construct the class using a list of particles:
2) get the rmsd using the method get_rmsd(trans3D1,Âtrans3D2)Â
whereÂtrans3D1 andÂtrans3D2 are rigid body transformations of the
reference and displaced configurations, respectively.
Simple Example: ....
It would be cool if the short description appears in the search
page, along with the class name.
Let's go to the second function:ÂÂIMP::statistics::ConfigurationSetRMSDMetric
Compute the RMSD between specified sets of particles in pairs of configurations, within a configuration set
this is even more cryptic. Maybe:Â
Calculates the RMSD of a list of particles between all possible configurations pairs in a "configuration set", which is....
Strangely, this class has not get_rmsd(), but get_distance() method....
Is that the same?
Let's go to another example:ÂIMP::atom::get_pairwise_rmsd_score
The measure quantifies the RMSD between the relative placements of two components compared to a reference relative placement. First, the two compared structures are brought into the same frame of reference by superposing the first pair of equivalent domains (ref1 and mdl1). Next, the RMSD is calculated for the second component
What are the components? Maybe subunits? What are the domains? Why the function is called rmsd_score? Is that different from the rmsd?
Ok I can go on for almost every function and method in IMP.
At the end, I'm completely unsure of what function I should use
for my task.... they all look the same.
Here's my proposal: Every function documentation must have these entries:
Short Description:Â(appears in the search page)
[Algorithm Description:Âin some cases]
The developer might leave these fields empty, of course.Â
When I search something, the first entries should be theÂ
ones which are more relevant and documented.
Or maybe, the search page should have Documented and Undocumented results.Â
(where Undocumented is a function which is lacking a long documentation page).
Of course we cannot force people to write comprehensive documentation,
but at least we can give the user the option of choosing the functions which
are better documented: that will be bad for developers that write code which is
undocumented, since their code will never be used by somebody else.
As a user, I will be skeptical using something where the documentation fieldsÂ
Sorry, that was long. Hope to hear your feedbacks