[boost] Re: Property_map docs

From: Edward Diener (eddielee_at_[hidden])
Date: 2002-11-10 10:26:02

OK, here are some questions regarding the property map library;

1) What is a property map ? Is it a template class, a class, a template
function, a function ?
2) What does the word "property" mean in the context of the name ?
3) What is the difference between property map and std::map<> ?
4) How does one use a property map ?
5) How does one create a property map of one's own ?
6) What are the prototypes for the get(), put(), and operator[] functions,
and are these really global functions as the doc suggests or are they
functions in the boost namespace ?
7) What do the various categories actually do for property maps ?

I do not believe that any of these questions are answered clearly in the
property map documentation
although they are all basic points which should be explained to the end
user. I know there is a concept there of mapping keys to values but beyond
that the documentation seems abstruse at best and needlessly irritating at
worst.

Please Boosters <g>, think about explaining your ideas to the programming
world in ways that they understand and can use, rather than in
metaprogramming terminology which only a select few know. Good documentation
is as important, in its own way, as good code.

"David Abrahams" <dave_at_[hidden]> wrote in message
news:uheeq41oo.fsf_at_boost-consulting.com...

>
> "Edward Diener" <eddielee_at_[hidden]> writes:
>
> > I don't understand property_maps. I think the documentation is
> > written in a sort of metaprogramming language which precludes its
> > use by most programmers, in a way that is different from the
> > language in which one usually understands the STL or most of the
> > other Boost libraries as an end user.
> >
> > I would like to urge boost implementors to write their documentation
> > first in a language that is for end users to understand and only
> > then have advanced sections for other implementors to use. As an
> > example of what I think is excellent Boost documentation, I will
> > point to Jaako Jarvi's tuple and lambda docs. I am sure Mr. Siek is
> > brilliant and knowledgable but his docs on property_map leave me
> > gasping for air. Perhaps the fault is mine.
>
> While you may (or may not) be right and justified in your remarks,
> your criticism is not constructive. The property map documentation is
> written in the same terms as the documentation for "the STL or most of
> the other Boost libraries", so it's very hard to imagine what your
> problem might be. Please ask specific questions that will help Jeremy
> to understand what specifically needs to be clarified.
>
> --
>                        David Abrahams
>    dave_at_[hidden] * http://www.boost-consulting.com
> Boost support, enhancements, training, and commercial distribution
>
> _______________________________________________
> Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost
>