[boost] Re: Re: Re: Property_map docs

From: Edward Diener (eddielee_at_[hidden])
Date: 2002-11-11 19:25:13

"Jeremy Siek" <jsiek_at_[hidden]> wrote in message
news:Pine.GSO.4.44.0211110951350.6135-100000_at_zaphod.osl.iu.edu...
> 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.

I apologize for sounding accusatory. I don't understand what you are at with
property_map although I discern a good idea in there. I just don't
understand why you are unwilling to explain it in terms that others can use
more easily. I know that I am missing how the mechanism works which links
the property_map concept to the get(), put(), and operator[] functions.

It is your idea and your documentation. If you feel that the documentation
is fit for the use of others, so be it. I will move on to other libraries
which I can understand. But I would like you to think about the possibility
that what you perhaps understand intuitively, others don't because they
don't have the information necessary to use your idea.

I don't want to ever discourage you or any others from contributing to an
organization so devoted to software excellence as Boost is. I am truly sorry
if any nastiness crept into the discussion in my efforts to understand your
software.

>
> 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]
> ----------------------------------------------------------------------
>
>
> _______________________________________________
> Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost
>