Re: [boost] Re: Re: Property_map docs

From: Victor A. Wagner, Jr. (vawjr_at_[hidden])
Date: 2002-11-11 03:54:57

for some reason that I can't really put my finger on, I found your reply 
offensive.

At Sunday 2002/11/10 23:19, you wrote:
>"Jeremy Siek" <jsiek_at_[hidden]> wrote in message
>news:Pine.GSO.4.44.0211102333330.4424-100000_at_zaphod.osl.iu.edu...
> > Hi Edward,
> >
> > On Sun, 10 Nov 2002, Edward Diener wrote:
> > eddiel> OK, here are some questions regarding the property map library;
> > eddiel>
> > eddiel> 1) What is a property map ? Is it a template class, a class, a
> > eddiel> template function, a function ?
> >
> > It is a "concept", as the term is used in the SGI STL docs:
> > http://www.sgi.com/tech/stl/stl_introduction.html
> > It has to do with specifying the contract between generic algorithms
> > (function templates) and the user of such algorithms.
>
>I am aware of your defintion of "concept" from Matt Austern's fine book. But
>concepts imply implementations.

I don't believe I've read Matt Austern's fine book, so I can't compare his 
concept of concept with what I get from reading Jeremy's documentation.  I 
will point out that simply because concepts imply implementations (a 
premise I'm not sure I accept), doesn't mean that any implementations 
actually exist.  There ARE some examples of implementations of this 
concept, but I don't see how that's relevent to the discussion of a concept 
itself.

> >
> > If you were looking for some useful concrete component to implement some
> > kind of mapping, then I'm afraid you will be disappointed in the property
> > map library.
>
>I am disappointed in the doc. The concept sounds interesting but I have no
>idea how it is implemented or used in a real situation.

It is a valid complaint that you don't know how to USE the concept, but not 
that you cannot implement it.

> >
> > eddiel> 2) What does the word "property" mean in the context of the name ?
> >
> > Here by property we mean something that is associated with some object. I
> > know this is vague, but there just is not much to the property map
> > concept.
>
>Yes, it is vague. Does that make you happy about it ?

What does Jeremy's happiness have to do with the value of the documentation?
Abstract things simply aren't concrete.  How concrete an explanation is 
possible?

> >
> > eddiel> 3) What is the difference between property map and std::map<> ?
> >
> > std::map<> is a class. property map is a concept (well, a collection
> > of concepts). You can use the boost::associative_property_map
> > adaptor to adapt std::map<> into a type that *models* property map.
>
>OK, why not explain that in the doc and how it is done.

I believe the example code does exactly what you ask.

> >
> > eddiel> 4) How does one use a property map ?
> >
> > You write function templates with template parameters that
> > have property map as their requirement.
>
>Example of this in the doc please.

While I'm also curious how to write (function/class) templates with 
parameters that have requirements, I'm not sure that THIS document is the 
proper place for that information.

> >
> > eddiel> 5) How does one create a property map of one's own ?
> >
> > Create a class and then define get(), put() and operator[]
> > function for the class.
>
>Example of this in the doc please.

You know, if every document we ever have stood by itself and went all the 
way down to "basics" (whatever those are...do we need to go down to the 1's 
and 0's of some extant machine to satisfy your requirment?), documentation 
would be MUCH larger than it is now.  Fortunately we normally get to 
_refer_ to other things and we figure the average reader can understand 
what's being said (or written).

> >
> > eddiel> 6) What are the prototypes for the get(), put(), and operator[]
> > eddiel> functions, and are these really global functions as the doc
> > eddiel> suggests or are they functions in the boost namespace ?
> >
> > They can live anywhere that argument dependent lookup can find them, which
> > means just about anywhere.
>
>You didn't answer the first question.

although they weren't explicitly shown "in the doc"
they are certainly visible by their use in the function foo
do you really need a more formal declaration of their prototypes?

> >
> > eddiel> 7) What do the various categories actually do for property maps ?
> >
> > Like the iterator tags in the C++ std, they allow function templates to
> > dispatch to different code depending on the category of the property map.
>
>Example of this in the doc please, with some function template showing this
>technique as practical usage within your "concept".

Again, I don't think that all documents need to show everything expecially 
if other examples already exist.
Did you go look at any usages of iterator tags?

> >
> > eddiel> I do not believe that any of these questions are answered clearly
> > eddiel> in the property map documentation although they are all basic
> > eddiel> points which should be explained to the end user. I know there is
> > eddiel> a concept there of mapping keys to values but beyond that the
> > eddiel> documentation seems abstruse at best and needlessly irritating at
> > eddiel> worst.
> > eddiel>
> > eddiel> Please Boosters <g>, think about explaining your ideas to the
> > eddiel> programming world in ways that they understand and can use, rather
> > eddiel> than in metaprogramming terminology which only a select few know.
> > eddiel> Good documentation is as important, in its own way, as good code.
> >
> > I've taken another look at the docs, and I'm afraid I do not see a lot of
> > room for improvement. The docs say pretty much what I said above, and
> > include links to resources where one can learn more about generic
> > programming.
> >
> > The property map library is by nature abstract. The main point of the
> > library is not to provide concrete classes, but instead to describe a
> > whole family of classes so that they can be used interchangeably in
> > function templates (generic algorithms).
> >
> > The property map library is for generic programming, and is described
> > using the terminology of generic programming. If you aren't doing generic
> > programming, then you don't need the property map library.
>
>I think you have taken an end run around the problem of your documentation.

_I_ don't see a problem.

>Rather than explain how to use your concept in detail to do generic
>programming, you want to insist that you have explained it adequately for
>other implementors to use it and that is what matters to you. OK, I will
>move on. I find it useless to fight with those who feel that the
>documentation is only for others "in the know" and not for the uninitiated.

One doesn't write documention for the clueless.

>I see universities connected with your name. Having gone to colleges myself
>many moons ago, I find it unbelievable that any college would accept your
>documentation as adequate explanation of your concept. Either colleges have
>deteriorated from what they were when I went there, or you don't perceive
>the need for the same amount of professionalism in dealing with other
>programmers as you would in dealing with college standards.

I on the other hand, have NO universities or colleges associated with my 
name (that I'm aware of).
Back when I was that age, I'm not sure that ANY school even knew what 
"computer science" was.
Maybe you have a legal case for fraud against your schools for not teaching 
you that you have to _continue_ to learn instead of stopping once you get 
the "degree".

I've figured out what it was about your message that irked me to respond.
Only once did you refer to YOUR abilities in a possibly negative way "I 
have no idea how it is implemented or used in a real situation".  In the 
rest of the message you insist that "things are wrong with the documentation".
A hint that _maybe_ the problem was with the reader instead of the writer 
probably would have kept me from responding.

Victor A. Wagner Jr.      http://rudbek.com
PGP RSA fingerprint = 4D20 EBF6 0101 B069 3817 8DBF C846 E47A
PGP D-H fingerprint = 98BC 65E3 1A19 43EC 3908 65B9 F755 E6F4 63BB 9D93
The five most dangerous words in the English language:
               "There oughta be a law"