Re: [IMP-dev] on documentation

[Javier Velazquez-Muriel <javi@salilab.org>]

Here are my comments:
> - in general, you need to read the documentation of all the bases 
> classes of a class and the module before you will understand the 
> class. I think this cannot be reasonably avoided.
Agreed

>  ConfigurationSetRMSDMetric would make more sense in light 
> understanding statistics::Metric. For example, it has no get_rmsd() 
> method since it is a specialization of the Metric base class and that 
> defines a get_distance() virtual method, so having a get_rmsd() method 
> would be useless where it is supposed to be used.
> -  What I would really like to see is that when someone spends the 
> time to figure something out like this, they add an example/patch the 
> comments in the files and then sends the patch off to someone to 
> integrate :-)
I wouldn't like to see any of these situations. If functions were 
documented (by the writer), the user wouldn't have to figure out 
anything or write patches. I agree with Riccardo also, a lot of 
functions in IMP (mine included) are cryptic, or require some knowledge.

> - I'd like to move to a more structured commit model for IMP with some 
> more review of things that go in so that we can prod people (and me) 
> more to improve docs/merge redundant things. I typed up some thoughts 
> on modifying the comment model here 
> <https://github.com/salilab/imp/wiki/A-proposed-commit-model-for-IMP> 
> Feel free to edit (or request permissions to edit, I'm a bit unclear 
> on how those are regulated :-) The main idea would be that if things, 
> in general, have two people look at them before going into most 
> modules in IMP, they should be a bit more coherent and documented. 
> And, if one is able to share things prior to committing them to the 
> SVN repository, they can stay in purgatory a bit longer (and will 
> hopefully be worked on a bit longer), before they considered good 
> enough and work on them ceases (as tends to happen). Not sure if this 
> will work :-)
Just a practical comment o this. If were are going to do all these 
changes, please let's switch to git as soon as possible. Learning 
another tool (git-svn or git flow) that is just an intermediate solution 
is a mess and has problems: For example, I talked to Ben and Daniel 
about moving developments not in the main repository between computers 
(mine and the cluster) and the options were suboptimal (use private git 
repositories, deal with github ...).  I tried to use them anyway, and I 
just gave up because of the commit hooks:
http://jinntech.blogspot.com/2009/11/git-svn-and-failed-svn-commit-hooks.html