[Olena-patches] cleanup-2008 2008: Add some documentation about site set properties.

https://svn.lrde.epita.fr/svn/oln/branches/cleanup-2008/milena Index: ChangeLog from Thierry Geraud &lt;thierry.geraud(a)lrde.epita.fr&gt; Add some documentation about site set properties. * mln/trait/site_set/props.hh: Add some doc. * mln/trait/site_sets.hh: Likewise. site_set/props.hh | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++---- site_sets.hh | 21 ++++++++++++ 2 files changed, 103 insertions(+), 6 deletions(-) Index: mln/trait/site_set/props.hh --- mln/trait/site_set/props.hh (revision 2007) +++ mln/trait/site_set/props.hh (working copy) @@ -37,6 +37,43 @@ # include <mln/trait/undef.hh> + +// Properties of site sets. +// ======================== + +// nsites: /any/ +// | +// + -- unknown +// | +// + -- known + +// bbox: /any/ +// | +// + -- unknown +// | +// + -- /known/ +// | +// + -- lazy +// | +// + -- straight + +// contents: /any/ +// | +// + -- fixed +// | +// + -- /dynamic/ +// | +// + -- growing +// | +// + -- free + +// arity: /any/ +// | +// + -- unique +// | +// + -- multiple + + namespace mln { @@ -46,34 +83,73 @@ namespace site_set { + + /// Site set property about the 'nsites' method presence. struct nsites { - struct any {}; + /// Base class for the site set 'nsites' property. + struct any { protected: any() {} }; + + /// Property that states that the number of sites cannot be + /// retrieved from a site set in O(1) complexity so the site + /// set does not feature the 'nsites' methods. struct unknown : any { std::string name() const { return "nsites::unknown"; } }; + + /// Property that states that a site set features the method + /// 'nsites' because the number of sites is known so its + /// retrieval has O(1) complexity. struct known : any { std::string name() const { return "nsites::known"; } }; }; + + /// Site set property about the 'bbox' method presence. struct bbox { - struct any {}; + /// Base class for the site set 'bbox' property. + struct any { protected: any() {} }; + + /// Property that states that the bounding box of a site set + /// is not featured as a method. This is either because the + /// notion of bounding box is meaningless for the site set + /// type, or because the bounding box cannot be retrieved in + /// O(1) complexity. struct unknown : any { std::string name() const { return "bbox::unknown"; } }; - struct known : any {}; + + /// Property that states that the bounding box of a site set + /// is featured by the 'bbox' method. It means that the + /// notion of bounding box makes sense and that such a piece + /// of information can be retrieved in O(1) complexity. + /// Warning: this property is pseudo-abstract. The more + /// precise properties are 'lazy' and 'straight'. + struct known : any { protected: known() {} }; + + /// Property that states that the bounding box of a site set + /// is computed by the site set in a lazy way. struct lazy : known { std::string name() const { return "bbox::lazy"; } }; + + /// Property that states that the bounding box of a site set + /// is always kept up to date by the site set. struct straight : known { std::string name() const { return "bbox::straight"; } }; }; + + /// Site set property about how the contents can evolve. struct contents { - struct any {}; + /// Base class for the site set 'contents' property. + struct any { protected: any() {} }; struct fixed : any { std::string name() const { return "contents::fixed"; } }; - struct dynamic : any {}; + struct dynamic : any { protected: dynamic() {} }; struct growing : dynamic { std::string name() const { return "contents::growing"; } }; struct free : dynamic { std::string name() const { return "contents::dynamic"; } }; }; + /// Site set property about the unicity or multiplicity of its + /// elements. struct arity { - struct any {}; + /// Base class for the site set 'arity' property. + struct any { protected: any() {} }; struct unique : any { std::string name() const { return "arity::unique"; } }; struct multiple : any { std::string name() const { return "arity::multiple"; } }; }; Index: mln/trait/site_sets.hh --- mln/trait/site_sets.hh (revision 2007) +++ mln/trait/site_sets.hh (working copy) @@ -37,9 +37,20 @@ # include <mln/trait/site_set/props.hh> +/// Shortcut to the site set property about the 'nsites' method +/// presence. # define mln_trait_site_set_nsites(S) typename mln::trait::site_set_< S >::nsites + +/// Shortcut to the site set property about the 'bbox' method +/// presence. # define mln_trait_site_set_bbox(S) typename mln::trait::site_set_< S >::bbox + +/// Shortcut to the site set property about how the contents can +/// evolve. # define mln_trait_site_set_contents(S) typename mln::trait::site_set_< S >::contents + +/// Shortcut to the site set property about the unicity or +/// multiplicity of its elements. # define mln_trait_site_set_arity(S) typename mln::trait::site_set_< S >::arity @@ -50,6 +61,7 @@ namespace trait { + /// Pack of 'undefined' type values for properties of site sets. template <typename I> struct undefined_site_set_ { @@ -59,6 +71,15 @@ typedef undef arity; // Unique or multiple. }; + + /*! \brief The trait pack structure for properties of site sets. + * + * This structure is specialized for every concrete class of site + * set so that properties are properly defined. + * + * \see mln::doc::Site_Set for the documentation of the "site set" + * concept. + */ template <typename I> struct site_set_ : undefined_site_set_<I> {