Hi David, Firstly I should qualify the following by saying that I havent yet spent as long as I should have on the subject of Concept documentation yet and am continuing to RTM(s). "David Abrahams" wrote
"Andy Little" <andy@servocomm.freeserve.co.uk> writes:
"David Abrahams" wrote
"Andy Little" <andy@servocomm.freeserve.co.uk> writes:
Your criticism mainly concerned the C++ Concepts section of the documentation for PQS. What might help is some examples of what you consider good C++ Concept documentation.
The C++ standard does a pretty decent job. There's also the SGI STL website. There's also the Boost Graph library. The "new iterator concepts" document in the iterator library docs does pretty well. And you can always start at http://www.boost.org/more/generic_programming.html#concept.
I have had a look at these sources and I will look at them in more detail, however they seem to represent only Concepts with runtime requirements.
I don't think so.
X a(b);
that the syntax is valid is a compile-time requirement. Any associated semantics are runtime requirements.
std::iterator_traits<T>::value_type
100% compile-time requirement.
Many of the concepts used in PQS library have only compile time requirements. The only example of documentation for this type of Concept that I know of is MPL.( I assume you see MPL as a good example of compile time only concept documentation).
Yes, **in the context of the MPL**. There is a background assumption that nested members of templates are types and not values, which you can't reasonably make in the PQS context.
Is there not a universal syntax for C++ concept documentation to which everyone should conform or in which every construct can be expressed?
PQS uses both forms of Concept. Is there any means or language convention to distinguish the two forms?
There are not really two different forms AFAICT.
OK. I have difficulties with that because it seems to contradict your remark about **in the context of MPL**. MPL is exclusively a compile time library. The TMP in PQS borrows heavily form MPL. If I implement more planned features of the PQS library, I will need runtime and compile time versions of many Concepts. An example of this is (lets call it ) DimensionA Concept which in the TMP book Dimensional Analysis example is modelled by the mpl::vector of dimensional exponents. In PQS it is also desirable to have a runtime version, this time modelled (say for simplicity) by something encapsulating a std::vector<int>. This would be a model of (lets call it) DimensionB. The two Concepts need to be distinguished. I'm not sure if there is a naming convention in use to distinguish the two. I thought of a Meta prefix for the DimensionA category (MetaDimension) and none for the latter (just Dimension). OTOH I thought of a namespace prefix meta::Dimension, but I think that would be unconventional. I read you werent happy about use of the word meta but it seems to have the right connotations to me FWIW, Const might do but I think the difference between these two is not well described by that.
My current intention is to put the compile-time requirement Concepts under a separate section from the runtime requirement Concepts.
Almost every concept you write that has runtime requirements also has compile-time requirements, so I don't know if this division makes much sense. But I'm much more concerned with the contents of the concept descriptions than the order in which they're presented.
I have put my latest effort at getting one PQS Concept (AbstractQuantity) right, into the Boost vault in Physical Quantities Units/ AbstractQuantity.html. http://tinyurl.com/7m5l8 BTW I am aware the formatting is poor, and external links go nowhere but currently I am just trying to get the syntax right (or more accurately the right ballpark) FWIW in rewriting PQS library, I am now aiming to make the Concepts wide enough so that the examples using mpl::vectors in TMP book should work though they will need specialisations(overloads?) of the metafunctions in the PQS Requirements to work of course. I guess this may have been what you were getting at in your review of PQS? IOW Some parts of the PQS library provide models of the Concepts, while other parts (metafunctions act in terms of Concepts) so can be applied to other models than the ones supplied. ------------ The following is some questions I am trying to answer. Maybe they just reflect my current confusion over this whole subject. Anyway I thought they might be interesting to see my struggles as a newcomer to this subject. I am currently looking over examples and may find answers to some questions there. Questions resulting from trying to do the AbstractQuantity Concepts in the above mentioned AbstractQuantity.html Associated metafunctions 1) Should I use the term return type with metafunctions? e.g typedef f<T>::type result; I see the above in terms of a function f returning a type, which IMO is quite acceptable in the TMP domain. I would then have a Returns clause in the specification describing the return type of f. It seems to be used this way in MPL docs anyway. 2) Overloaded metafunctions. I have overloaded? specialised? the metafunctions in a similar way to runtime functions are overloaded. An obvious example is the pqs::meta::binary_operation metafunction in the sample. This is meant to be entirely equivalent to runtime operator functions such as operator +. ( std::string + std:: string , int + int , IOW its just an operator) Now however I need to express the overload of the Concept arguments. The way it seems to be done is to put in some Preamble (Sometimes called Notation?) that in the following, Lhs and Rhs are models of Concept X. The problem is that is remote from the per item description: binary_operation<Lhs,Op,Rhs> IMO It would make more sense to say e.g. binary_operation<AbstractQuantity Lhs,Op,AbstractQuantity Rhs> 3) Why no BooleanConstant Concept? boost::typetraits uses true_type_or_false_type. MPL uses IntegralConstant Concept. Should there be a (say) BooleanConstant Concept? (Also IMO then there should be a True Concept and a False concept) This would be more generic and could apply to MPL and type_traits return types. 4)Am I right in saying there is a fair amount of variability in Concept documentation?. It strikes me that there could be a more abstract syntax to describe Concepts. Many times I want to say for example: T Is True , meaning that in code where true_ is some model of True then one (among several) ways for a type t to model this Concept is struct c : true_ {}; regards Andy Little