|
|
Am 19.05.2011 05:06, schrieb SGeier:
>> clipped_by is implemented as follows:
>>
>> (1) The base object's intersection(s) with the ray are determined;
>>
>> (2) for each intersection it is checked whether it is inside the
>> clipped_by object.
>>
>> Any intersections not reported by step (1) are ignored.
>
> Good to know that this is how it is implemented. However this is NOT how it
> is documented. Put the above paragraph into the documentation and
> implementation and documentation are in agreement.
If you think the documentation is bad, then you're happily invited to
help make it better.
It's not like the developers & other people helping with POV-Ray would
be paid anything for it; our only payment is the joy of doing it (and
every programmer knows that implementation work is more fun than writing
documentation), the joy of seeing people get good results of it, and the
joy of receiving some motivating feedback from the community now and then.
So if you /want/ anything from us, or want to /insist/ on some point of
view that the dev team does not share, you're in the wrong place.
> I would hope so - that's why I post things here that do not work as
> documented.
It's one thing to get feedback on things that people /think/ is wrong.
Getting feedback from someone who /knows better/ (or at least sounds
like that) is something entirely different.
> There's a perennial communications problem between programmers and users: To
> the programmer, the code is the end-all and be-all. Whatever the code does
> is "true" and if the documentation deviates from it, then the documetation
> is wrong. However from the user perspective, the documentation is all there
> is - it tell me what is *supposed* to happen and if the observed results are
> different then the code is buggy.
No. To the programmer, the /intention/ is the end-all and be-all. If the
code fails to match that, it is buggy. If the documentation fails to
match that, it is either wrong (making an explicit statement that is not
true), incomplete (failing to make an explicit statement that is true
bot not necessarily obvious to the user), or imprecise (making a
statement that can be interpreted in a way that is true, but also in
another way that is not).
In this particular case, the documentation is /incomplete/, but not
wrong: It does /not/ make an explicit statement about the situation you
encountered. It does however make a statement about similar situations
with CSG, which /might/ give resourceful users a hint what's going wrong
with regard to clipped_by.
BTW, to the end user, the /expectation/ is the end-all and be-all; the
documentation can only serve to modify those expectations. So if some
docs do not explicitly mention the program's behaviour in a very rare
situation, who is outright /wrong/: The documentation, or the user's
expectations? I dare say the latter, because the docs simply cannot
foresee all that a user may expect.
Also note that in real life there is no such thing as a /complete/
documentation.
> If the wording in the docs leads the reader to expect behaviour different
> from what is implemented, then the wording is far enough from ideal that we
> might as well call it false.
I disagree in some points:
(1) The docs do not /lead/ the reader to expect behaviour different from
what is implemented in this case. It is /your/ expectation, and all you
can blame the documentation for is that it did not /lead you away/ from
that expectation. Provided that you even gave it a chance to do so, by
thoroughly reading the isosurfaces doc section.
(2) I guess that careful reading of the doc section on isosurfaces
/will/ lead the majority of readers away from that expectation, at least
to the degree that they're not too surprised when their original
expectation proves wrong.
(3) My definition of a "false" documentation is more strict than yours
seems to be. In my terminology, "incomplete" or "imprecise" is not
necessarily "false".
> If that is "as intended", then this intention needs to be communicated (in
> the docs, not here).
(4) There is no /need/ to communicate the programmers' intentions to the
users. It's probably /helpful/, but there is no such /obligation/ to the
dev team - neither legally (see the license) nor morally (what you get
from the dev team is a free gift, and you can either take it or leave
it, and there's nothing you can /demand/ on top).
Post a reply to this message
|
|