Re: [boost] Re: Re: Property_map docs

From: Jeremy Siek (jsiek_at_[hidden])
Date: 2002-11-11 10:01:01

Hi Edward,

Since you feel so strongly about this, please write a new version of the
property map docs and send them to me.

In future emails, I would appreciate it if you refrained from using such
an accusatory tone. At this point I'm feeling hurt by your words and
discouraged about volunteering my time to boost.

Sincerely,
Jeremy

On Mon, 11 Nov 2002, Edward Diener wrote:
eddiel> "Jeremy Siek" <jsiek_at_[hidden]> wrote in message
eddiel> news:Pine.GSO.4.44.0211102333330.4424-100000_at_zaphod.osl.iu.edu...
eddiel> > Hi Edward,
eddiel> >
eddiel> > On Sun, 10 Nov 2002, Edward Diener wrote:
eddiel> > eddiel> OK, here are some questions regarding the property map library;
eddiel> > eddiel>
eddiel> > eddiel> 1) What is a property map ? Is it a template class, a class, a
eddiel> > eddiel> template function, a function ?
eddiel> >
eddiel> > It is a "concept", as the term is used in the SGI STL docs:
eddiel> > http://www.sgi.com/tech/stl/stl_introduction.html
eddiel> > It has to do with specifying the contract between generic algorithms
eddiel> > (function templates) and the user of such algorithms.
eddiel>
eddiel> I am aware of your defintion of "concept" from Matt Austern's fine book. But
eddiel> concepts imply implementations.
eddiel>
eddiel> >
eddiel> > If you were looking for some useful concrete component to implement some
eddiel> > kind of mapping, then I'm afraid you will be disappointed in the property
eddiel> > map library.
eddiel>
eddiel> I am disappointed in the doc. The concept sounds interesting but I have no
eddiel> idea how it is implemented or used in a real situation.
eddiel>
eddiel> >
eddiel> > eddiel> 2) What does the word "property" mean in the context of the name ?
eddiel> >
eddiel> > Here by property we mean something that is associated with some object. I
eddiel> > know this is vague, but there just is not much to the property map
eddiel> > concept.
eddiel>
eddiel> Yes, it is vague. Does that make you happy about it ?
eddiel>
eddiel> >
eddiel> > eddiel> 3) What is the difference between property map and std::map<> ?
eddiel> >
eddiel> > std::map<> is a class. property map is a concept (well, a collection
eddiel> > of concepts). You can use the boost::associative_property_map
eddiel> > adaptor to adapt std::map<> into a type that *models* property map.
eddiel>
eddiel> OK, why not explain that in the doc and how it is done.
eddiel>
eddiel> >
eddiel> > eddiel> 4) How does one use a property map ?
eddiel> >
eddiel> > You write function templates with template parameters that
eddiel> > have property map as their requirement.
eddiel>
eddiel> Example of this in the doc please.
eddiel>
eddiel> >
eddiel> > eddiel> 5) How does one create a property map of one's own ?
eddiel> >
eddiel> > Create a class and then define get(), put() and operator[]
eddiel> > function for the class.
eddiel>
eddiel> Example of this in the doc please.
eddiel>
eddiel> >
eddiel> > eddiel> 6) What are the prototypes for the get(), put(), and operator[]
eddiel> > eddiel> functions, and are these really global functions as the doc
eddiel> > eddiel> suggests or are they functions in the boost namespace ?
eddiel> >
eddiel> > They can live anywhere that argument dependent lookup can find them, which
eddiel> > means just about anywhere.
eddiel>
eddiel> You didn't answer the first question.
eddiel>
eddiel> >
eddiel> > eddiel> 7) What do the various categories actually do for property maps ?
eddiel> >
eddiel> > Like the iterator tags in the C++ std, they allow function templates to
eddiel> > dispatch to different code depending on the category of the property map.
eddiel>
eddiel> Example of this in the doc please, with some function template showing this
eddiel> technique as practical usage within your "concept".
eddiel>
eddiel> >
eddiel> > eddiel> I do not believe that any of these questions are answered clearly
eddiel> > eddiel> in the property map documentation although they are all basic
eddiel> > eddiel> points which should be explained to the end user. I know there is
eddiel> > eddiel> a concept there of mapping keys to values but beyond that the
eddiel> > eddiel> documentation seems abstruse at best and needlessly irritating at
eddiel> > eddiel> worst.
eddiel> > eddiel>
eddiel> > eddiel> Please Boosters <g>, think about explaining your ideas to the
eddiel> > eddiel> programming world in ways that they understand and can use, rather
eddiel> > eddiel> than in metaprogramming terminology which only a select few know.
eddiel> > eddiel> Good documentation is as important, in its own way, as good code.
eddiel> >
eddiel> > I've taken another look at the docs, and I'm afraid I do not see a lot of
eddiel> > room for improvement. The docs say pretty much what I said above, and
eddiel> > include links to resources where one can learn more about generic
eddiel> > programming.
eddiel> >
eddiel> > The property map library is by nature abstract. The main point of the
eddiel> > library is not to provide concrete classes, but instead to describe a
eddiel> > whole family of classes so that they can be used interchangeably in
eddiel> > function templates (generic algorithms).
eddiel> >
eddiel> > The property map library is for generic programming, and is described
eddiel> > using the terminology of generic programming. If you aren't doing generic
eddiel> > programming, then you don't need the property map library.
eddiel>
eddiel> I think you have taken an end run around the problem of your documentation.
eddiel> Rather than explain how to use your concept in detail to do generic
eddiel> programming, you want to insist that you have explained it adequately for
eddiel> other implementors to use it and that is what matters to you. OK, I will
eddiel> move on. I find it useless to fight with those who feel that the
eddiel> documentation is only for others "in the know" and not for the uninitiated.
eddiel>
eddiel> I see universities connected with your name. Having gone to colleges myself
eddiel> many moons ago, I find it unbelievable that any college would accept your
eddiel> documentation as adequate explanation of your concept. Either colleges have
eddiel> deteriorated from what they were when I went there, or you don't perceive
eddiel> the need for the same amount of professionalism in dealing with other
eddiel> programmers as you would in dealing with college standards.
eddiel>
eddiel>
eddiel>
eddiel>
eddiel> _______________________________________________
eddiel> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
eddiel>

----------------------------------------------------------------------
 Jeremy Siek                          http://php.indiana.edu/~jsiek/
 Ph.D. Student, Indiana Univ. B'ton   email: jsiek_at_[hidden]
 C++ Booster (http://www.boost.org)   office phone: [phone]
----------------------------------------------------------------------