Re: [Nova-developer] Documentation for libnova

[Mike M. <ii...@gm...>]

Hi Liam and everyone.

On 01/03/06, Liam Girdwood <li...@gn...> wrote:

>> [--thoughts about documentation--]

> This would be very helpful, as the subject matter is very difficult for
> beginners to understand (it's even difficult if you have a copy of
> Meeus).

No argument about that.  I can see why Meeus' book is held in such
high regard as far as providing useful formulas, but I found it quite
frustrating just trying to learn about what was going on.  As well as
not spending much time explaining what things were as much as specific
equations to calculate them, he seemed to have a habit of arbitrarily
changing units of measurement half way through examples, and so on.=20
Since starting with that, I've built up a small library of other books
on the same topic, but haven't had much of an opportunity to get into
them yet.

> How do you propose doing this ? Would you use doxygen or do you have
> another documentation system in mind ?

I haven't figured it out at this point, but I've had an idea in the
back of my mind for a while that I'd like to write a getting-started
guide based around a big flow-chart that indicates all the steps to go
through for certain calculations, probably with a some detail (not an
essay) about each step, referencing the functions in the code that are
applicable, as well as documenting things like how expensive a step is
for calculation versus how significant it is for accuracy.  I've been
teaching myself about this on and off for the past six months, and I'm
still learning (so I'd expect someone might need to proof-read some of
the specifics for accuracy if I did write it), but I'm hoping that
such a perspective might help to decide notes that could be useful.


I hadn't thought as far as to what documentation system to use, but I
don't see why it couldn't fit into a doxygen format.  Perhaps the best
thing for me to do would be to just try and write something at all.=20
You could see what you think, and integrate it into the project if it
seems appropriate to do so.

It's likely to take at least a few weeks for me to get into this and
I'm reluctant to commit to too much straight away, plus I'd need to
familiarise myself with how libnova does things.  It's good to hear
that there's a general interest, though.


Mike.