I have finally got back to this after a long period of doing other things On 24 October 2012 16:08, Andre Merzky <andre@merzky.net> wrote:
Hi Steve,
On Wed, Oct 24, 2012 at 8:29 AM, Steve Fisher <dr.s.m.fisher@gmail.com> wrote:
2.1 Para 1 sentence 2 -> While we expect that language bindings will, in general, follow that hierarchy for Python it is not useful to do so.
I would argue that usefulness is something to be evaluated by the implementor. I, for one, find inheritance exceedingly useful, also in python ;-)
I had meant to shorten and simplify your sentence without changing its meaning. However I had shortened it too much. How about replacing the whole para with: The SAGA API defines an interface and class hierarchy which we normally expect language bindings to follow. In the case of Python some deviation produces a better result.
Omit 2.1 para 3
That is supposed to lead into 2.1.x, so needs at least some replacement.
I don't think it contains any essential linking material. If you wish to keep it then improve the grammar and don't mention duck-typing.
2.1.1 CAN -> MAY
Hmm, first you state quite strongly that inheritance is not useful, then you discourage the flattening option -- that does not fit? MAY means that this choice needs to be well motivated beyond the arguments in this document (kind of). Fine with me actually, but I think that is not consistent.
This is a misunderstanding. Inheritance is great - (except in C++ of course). You had the word CAN in caps which I presumed was meant to follow the rules of http://www.ietf.org/rfc/rfc2119.txt on the use of a few special words. I just suggested changing it to a standard word without changing the meaning.
2.1.2 Omit last two sentences
The last sentence is repetition, removed - but the sentence before is relevant, no?
It is not necessary and I see no need to introduce ducks
2.5 Omit this section - it will be hard to get right and will just cause confusion
I can see that - ok to add is as second appendix?
Try it - but my comments still stand!
Appendix A - This should start with an explananation of how to interpret what follows
Makes sense.
Thanks, Andre.
I will send comments on the contents of Appendix A as a separate email
Steve
-- Nothing is really difficult...