[boost] Re: Re: Re: Property_map docs

From: Edward Diener (eddielee_at_[hidden])
Date: 2002-11-12 01:21:59

"Christoph Kögl" <christoph_at_[hidden]> wrote in message
news:1037063128.2680.0.camel_at_localhost.localdomain...
> Hi Jeremy (and Edward),
>
> I am just now reading that unfortunate Edward Diener thread. Normally I
> am a quiet Boost
> list/code consumer, but this is the time, I think, to speak up (a
> little), just to let you know
> that there are guys out here that very much appreciate Jeremy's
> contributions to Boost.

I appreciate Jeremy's Siek's other contributions also.

> Edward may have let his frustration take the better of him, and I really
> would like him
> to read through the BGL (Boost Graph Library) docs, because that's where
> property maps
> are used in abundance and where enough example code lives to make the
> concept
> clear. Hey, there even is a book on the BGL which probably (I have not
> read it) talks
> about property maps as well. So, please, Edward, refrain from
> prematurely posting harsh
> remarks about seemingly unsuitable documentation (and note: I am not
> saying anything about
> your not being able to grasp the concept of property maps, I instead
> suppose that you did not
> devote enough time to trying to do so). I, for my part, have been using
> the BGL (along with property
> map implementations) extensively of late, and I cannot say that I
> encountered undue difficulties with
> the BGL/PM docs.

The problem is that property map is presented separately from the BGL.
Therefore a valid assumption would be that one could understand how it works
separately from the BGL.

>
> Good night.
>
> PS. Edward, you may want to let us know what exactly your envisioned
> area of application of the property map concept is. Then we may be able
> to help you with
> your specific problem(s). Here are some short answers to some of your
> questions:

I have no envisioned area of application. I was just reading through various
Boost libraries trying to understand ideas and implementations and was
befuddled by the property map docs. It seemed to imply that one could use
generic algorithms to do mapping between a key and a value, and I like this
idea in general, but I couldn't understand the specifics of how this was
done and how it was used. The doc was saying to me "there is a way to use
this concept so just dig and investigate and look at the source code and you
will probably figure it out." That may not have been Mr. Siek's thought when
he wrote it but that was my reaction to it. To me that isn't acceptable as
documentation, so I wrote my criticism saying so. I will stand by my
criticism that it isn't the way to explain anything and should be improved.
Mr. Siek doesn't think so, and nobody else does either, so that's fine and I
needn't attempt to use it in any way for myself if I don't understand how to
use it.

 The concept sounds interesting but I
> have no
> > idea how it is implemented or used in a real situation.
>
> Well, the mathematical concept underlying property maps are maps (in the
> mathematical
> sense): let A, B be two sets, then a map m from A to B (denoted m: A->B)
> is a subset of
> AxB (the direct product of A and B) such that for ordered pairs (a,b),
> (a,c) of m we have that
> b=c holds (i.e. maps are left-unique binary relations). If you do not
> understand the concept
> of mathematical maps I am afraid you are out of luck (you =/= Edward
> here, just the anonymous
> "you"). Boost's property maps are one method to model mathematical maps
> in C++ that mandates
> not the use of one specific implementation (like some predefined
> class(es) of function(s)), rather they
> are "merely" a set of assumptions. Every C++ software artifact that
> fulfills these assumptions (read:
> abides by the specified syntactic and semantic requirements of the
> property map concept) is a
> property map. Software that in its code only uses the assumptions that
> the property map concept
> mandates (and not more) is guaranteed to work with /every/ artifact
> implementing the property map
> concept.

Thanks for the explanation. I do appreciate it.

> A more familiar case might be the concept of Input Iterator.
> The std::find algorithm works
> for every C++ artifact that implements the Input Iterator concept; you
> are not confined to use
> std::list::const_iterator, std::map::iterator etc., /any/ Input Iterator
> works (not just those from the
> standard library).

Input iterators have necessary implementations which are explained in
detail, or they won'[t work with the generic algorithms which use them.

> So, actually, contrary to what Jeremy says, the
> property map concept in itself
> is not at all vague. It /could/ be defined more rigorously (read:
> formally, which inevitably means
> mathematically, because mathematics really is the only precise language
> humankind currently has).
> But this is not necessary nor would greatly support its understanding
> for the average developer
> (simply because the average developer is not trained in reading precise
> formal specifications like
> algebraic data types, modal/temporal logic, process algebras, whatever).
> The understanding therefore
> must come from practice and from reading existing code.

I beg to differ. Understanding comes from human communication. It's this
idea that one must study code because programmers do not have the time or
patience to document adequately their ideas that I am reacting most strongly
against. I am not saying that this is Mr. Siek's case, but it appeared so to
me. If I didn't think highly of the Boost libraries and what talented and
creative individuals are doing in C++ I wouldn't have bothered criticising
anything.

OK, I am missing something in these docs which I expected to see and it is
not there for me. Evidently it is for everybody else and they consider it to
be adequate. I will say that no matter how poor the documentation seems to
me, it is probably on another level which I don't understand and which
others can easily figure out without any more specific explanation. I
apologize to all concerned and will simply bypass such implementations in
the future when the language of it is beyond my understanding. I thought
that by criticizing there would be others who might agree that the
documentation is not adequate for an intelligent C++ programmer to grasp,
and there would be an effort by either Mr. Siek, or someone else who
understands property map, to improve it and make it more understandable. I
was wrong and will leave it at that and wish everyone good luck in their
programming and documentation endeavors.