On 5/16/07, gary thompson <garyt.and.sarahb@xxxxxxxxx> wrote:
On 5/15/07, Edward d'Auvergne <edward.dauvergne@xxxxxxxxx> wrote:
> Yikes, that is a lot of added docstrings!!! Very impressive.
ah, but (more importantly), does it make sense to you ;-)
Sorry about the delay in responding. Once I get internet at home,
although that could be a month away, then I'll be able to respond more
rapidly. I have read some of the docstrings and it seems quite well
documented. A simple spell check might help a little with the
readability. Would you know if there is a way to describe what the
@see epydoc tags point to and why? There is a lot of jumping around
and it would be useful to know why the other functions are being
pointed to. It would be interesting to see if someone who hasn't seen
the code can understand the execution flow from the auto-generated API
documentation.
There are also a few variables which are named in a slightly confusing
way. For example the 'proccesor_size' argument to the
'load_multiprocessor' function. As this function is the first point
of entry, this docstring is quite important. It doesn't have a
'@param: ', and '@type: ' description in the docstring and, combined
with the name, could lead to confusion. For example is the size of
the processor measured in cm^2, cm^3, L, or inches^2 etc.? ;)
Another confusion, for me anyway, is the 'processor' module documentation:
"""
2. create an Application_callback object
"""
How should I create this? What object properties does the multi code
expect? Is it the object's __call__() method or __init__() method
which is executed? I wouldn't know where to start with this if I was
to use the 'multi' package with some other program.
> Have
> you tried compiling the API documentation to see how these comments
> will look?
no I haven't tried compiling yet, I intend to get to the end of
processor.py and give it a try. is it fairly easy?
With epydoc and scons installed, it is a single command in the base
relax directory:
$ scons api_manual_html
my current schedule is
1. complete docs for prcoessor.py (this is partially so Neil can read it, he
ios having atry at parallelising func, dfunc amd d2func for case all in
mf.py as a bit of a journeyman project, it doesn't really matter how far he
gets and if it works well in python [though it might])
2. fix neils bug in the multi branch (he sees non returned from some
minimisation which causes a crash)
3. go through the detail on the older e-mail you sent to me
4. complete docs
2 and 3 may swap depending on mood
Hopefully I can soon get the 1.3 line in a good enough shape for
porting to occur. Without the unit tests written, this refactoring
will be slow as I'll have to write the tests as I go. If anyone would
like help by writing unit tests for the 1.3 main line, the development
of this branch will be significantly accelerated :)
Cheers,
Edward
Re: r3295 - in /branches/multi_processor: multi/multi_processor.py multi/processor.py specific_fns/model_free.py