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" <[EMAIL PROTECTED]> wrote in message eddiel> news:Pine.GSO.4.44.0211102333330.4424-100000@;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: [EMAIL PROTECTED] C++ Booster (http://www.boost.org) office phone: (812) 855-3608 ---------------------------------------------------------------------- _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
