[Olena-patches] olena-2.0-541-g83d9bff Enhance documentation in scribo.

* scribo/core/component_set.hh, * scribo/core/object_links.hh: Add missing member documentation. * scribo/debug/logger.hh: Fix an invalid object reference. --- scribo/ChangeLog | 9 ++++++ scribo/scribo/core/component_set.hh | 5 ++- scribo/scribo/core/object_links.hh | 50 ++++++++++++++++++++++++++++------- scribo/scribo/debug/logger.hh | 2 +- 4 files changed, 53 insertions(+), 13 deletions(-) diff --git a/scribo/ChangeLog b/scribo/ChangeLog index cf030cb..9f4ac2a 100644 --- a/scribo/ChangeLog +++ b/scribo/ChangeLog @@ -1,5 +1,14 @@ 2013-04-17 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; + Enhance documentation in scribo. + + * scribo/core/component_set.hh, + * scribo/core/object_links.hh: Add missing member documentation. + + * scribo/debug/logger.hh: Fix an invalid object reference. + +2013-04-17 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; + * scribo/core/component_set.hh: Hide internal API. 2013-04-17 Guillaume Lazzara &lt;z(a)lrde.epita.fr&gt; diff --git a/scribo/scribo/core/component_set.hh b/scribo/scribo/core/component_set.hh index 259a508..30769d4 100644 --- a/scribo/scribo/core/component_set.hh +++ b/scribo/scribo/core/component_set.hh @@ -256,7 +256,7 @@ namespace scribo // Misc Members - /// Return the component count. + /// Return the number of components, background excluded. mln_value(L) nelements() const; /// Return component information for a given component id \p id. @@ -357,11 +357,12 @@ namespace scribo }; + /// \relates component_set template <typename L> bool operator==(const component_set<L>& lhs, const component_set<L>& rhs); - + /// \relates component_set template <typename L> std::ostream& operator<<(std::ostream& ostr, const component_set<L>& info); diff --git a/scribo/scribo/core/object_links.hh b/scribo/scribo/core/object_links.hh index 0515d84..ef1d3ab 100644 --- a/scribo/scribo/core/object_links.hh +++ b/scribo/scribo/core/object_links.hh @@ -58,7 +58,7 @@ namespace scribo object_links_data(); object_links_data(const component_set<L>& components, unsigned size); object_links_data(const component_set<L>& components, - unsigned size, unsigned value); + unsigned size, unsigned default_link_id); mln::util::array<unsigned> comp_to_link_; component_set<L> components_; @@ -69,20 +69,41 @@ namespace scribo - /// \brief Object links representation. - /// - /// \ingroup grpstruct - // + /*! \brief Object links representation. + + This structure is meant to store link information between + components. Linking components can be considered as a first step + towards component grouping. + + It requires a component_set to be constructed. Each component + existing in the component_set may have link in an object_link + structure. If no component_set is used for construction, this + object is invalid (\sa is_valid()). + + + + \ingroup grpstruct + */ template <typename L> class object_links : public Serializable<object_links<L> > { typedef internal::object_links_data<L> data_t; public: + /// Default constructor. It produces an invalid structure. object_links(); + + /// Construct a valid object_links. Links is enabled for each + /// valid component but no link is set. Invalid components links + /// are disabled. object_links(const component_set<L>& components); - object_links(const component_set<L>& components, unsigned value); + /// Construct a valid object_links. Links is enabled for each + /// valid component and set by default towards component with id + /// \p default_link_id. Invalid components links are disabled. + object_links(const component_set<L>& components, unsigned default_link_id); + + /// Return the underlying component_set. const component_set<L>& components() const; /// Return True if this object_links structure is correctly @@ -97,6 +118,8 @@ namespace scribo /// itself to another component. bool is_linked(unsigned comp_id) const; + /// Return the number of links. This is equivalent to the number + /// of components + the background. unsigned nelements() const; /// Link related methods. @@ -116,10 +139,16 @@ namespace scribo const unsigned& operator()(unsigned comp_id) const; /// \} + /// Returns the underlying array encoding the component + /// links. Indexes in array correspond to component ids and the + /// corresponding value is the component id involved in the link. const mln::util::array<unsigned>& comp_to_link() const; + /// Initialize links. Each component is linked to itself (i.e. has + /// no link). Invalid components have linking disabled. void init(); + /// Make a deep copy of this structure. object_links<L> duplicate() const; private: @@ -127,6 +156,7 @@ namespace scribo }; + /// \relates object_links template <typename L> std::ostream& operator<<(std::ostream& ostr, const object_links<L>& links); @@ -156,8 +186,8 @@ namespace scribo template <typename L> object_links_data<L>::object_links_data(const component_set<L>& components, - unsigned size, unsigned value) - : comp_to_link_(size, value), components_(components) + unsigned size, unsigned default_link_id) + : comp_to_link_(size, default_link_id), components_(components) { }; @@ -182,10 +212,10 @@ namespace scribo template <typename L> object_links<L>::object_links(const component_set<L>& components, - unsigned value) + unsigned default_link_id) { data_ = new data_t(components, value::next(components.nelements()), - value); + default_link_id); } diff --git a/scribo/scribo/debug/logger.hh b/scribo/scribo/debug/logger.hh index 0b29aaf..ab283c3 100644 --- a/scribo/scribo/debug/logger.hh +++ b/scribo/scribo/debug/logger.hh @@ -144,7 +144,7 @@ namespace scribo inside a program. Stopping time logging will output the computed time if - Verbose mode is higher or equal to #Time. + Verbose mode is higher or equal to scribo::debug::Time. */ /// @{ void start_time_logging(); -- 1.7.2.5