[boost] Re: Re: Property_map docs

From: Edward Diener (eddielee_at_[hidden])
Date: 2002-11-11 01:19:33

"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.

>
> 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.

>
> 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 ?

>
> 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.

>
> 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.

>
> 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.

>
> 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.

>
> 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".

>
> 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.
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.

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.