From: g0dil Date: Sat, 7 Aug 2010 08:45:46 +0000 (+0000) Subject: Documentation updates/fixes X-Git-Url: http://g0dil.de/git?p=senf.git;a=commitdiff_plain;h=45d5b4cfa79eee57d5de832960cdac2c6a114f71 Documentation updates/fixes git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@1664 270642c3-0616-0410-b53a-bc976706d245 --- diff --git a/senf/PPI/Connectors.hh b/senf/PPI/Connectors.hh index 2ca48be..bb0724e 100644 --- a/senf/PPI/Connectors.hh +++ b/senf/PPI/Connectors.hh @@ -389,9 +389,8 @@ namespace connector { dequeue a packet from the packet queue. If the connector is active, the connector will request new packets from the connected module. If the packet - request cannot be fulfilled, this is considered to be a - logic error in the module implementation and an - exception is raised. */ + request cannot be fulfilled an in-valid Packet is + returned. */ Packet read(); ///< Alias for operator()() diff --git a/senf/Utils/Console/Node.hh b/senf/Utils/Console/Node.hh index 286f516..a6d64c4 100644 --- a/senf/Utils/Console/Node.hh +++ b/senf/Utils/Console/Node.hh @@ -674,10 +674,49 @@ namespace console { DirectoryNode & provideDirectory(DirectoryNode & dir, std::string const & name); -#ifndef DOXYGEN +/** \brief Console node factories + + The senf::console::factory namespace (customarily aliased to \c fty in user code) contains + factories used to create new node types: + \code + namespace fty = senf::console::factory; + + senf::console::DirectoryNode & dir (node.add("dirname", fty::Directory())); + + dir.add("name", fty::Command(&fn) + .arg("flag") + .doc("documentation")); + \endcode + The node is added by passing the factory instance to senf::console::DirectoryNode::add(). + + To further customize the node, you may call attributor members on the temporary factory class + instance. Since the attributor members always return a self-reference to the factory class + instance, attributor calls may be chained arbitrarily. + + \see + \ref console_commands for details on the command nodes \n + \ref node_tree for details on the structural nodes (directory, link) + + \note All factories are documented here as classes when in fact some are functions returning + internal classes. + + \implementation It is not true, that all attributor members return a self reference. Some + attributor members will return a new object of slightly different type. However, the + behavior is as documented above. + + \ingroup console_commands + */ namespace factory { + /** \brief SimpleCommandNode factory + + This factory will create a SimpleCommandNode calling the given callback. A SimpleCommandNode + does not support overloading or automatic argument parsing. + + \attention This class is of interest mostly for testing and as a simple CommandNode + example. Use senf::console::factory::Command instead. + */ class SimpleCommand : public detail::NodeFactory { @@ -687,15 +726,32 @@ namespace factory { explicit SimpleCommand(SimpleCommandNode::Function fn); - SimpleCommandNode & create(DirectoryNode & dir, std::string const & name) const; - SimpleCommand const & doc(std::string const & doc) const; + ///< Set simple command documentation SimpleCommand const & shortdoc(std::string const & doc) const; + ///< Set simple command short documentation private: + SimpleCommandNode & create(DirectoryNode & dir, std::string const & name) const; + SimpleCommandNode::ptr node_; + + friend class senf::console::DirectoryNode; }; + /** \brief DirectoryNode factory + + This factory will create new directory nodes. Use + + \code + namespace fty = senf::console::factory; + node.add("mydir", fty::Directory()) + \endcode + + To add a directory \a mydir to \a node. + + \see \ref node_tree + */ class Directory : public detail::NodeFactory { @@ -705,15 +761,32 @@ namespace factory { Directory(); - DirectoryNode & create(DirectoryNode & dir, std::string const & name) const; - Directory const & doc(std::string const & doc) const; + ///< Set directory documentation Directory const & shortdoc(std::string const & doc) const; + ///< Set directory short documentation private: + DirectoryNode & create(DirectoryNode & dir, std::string const & name) const; + DirectoryNode::ptr node_; + + friend class senf::console::DirectoryNode; }; + /** \brief LinkNode factory + + This factory will create new link nodes. Use + + \code + namespace fty = senf::console::factory; + node.add("mylink", fty::Link(targetNode)) + \endcode + + To add a link \a mylink to \a node pointing to \a targetNode + + \see \ref node_tree + */ class Link : public detail::NodeFactory { @@ -723,16 +796,16 @@ namespace factory { explicit Link(GenericNode & target); + private: LinkNode & create(DirectoryNode & dir, std::string const & name) const; - private: LinkNode::ptr node_; + + friend class senf::console::DirectoryNode; }; } -#endif - }} ///////////////////////////////hh.e//////////////////////////////////////// diff --git a/senf/Utils/Console/ParsedCommand.hh b/senf/Utils/Console/ParsedCommand.hh index 6c443ba..e14fd1c 100644 --- a/senf/Utils/Console/ParsedCommand.hh +++ b/senf/Utils/Console/ParsedCommand.hh @@ -177,10 +177,6 @@ namespace console { { public: typedef boost::intrusive_ptr ptr; - -#ifdef DOXYGEN - static ptr create(Function fn); -#endif }; #ifndef DOXYGEN @@ -210,8 +206,6 @@ namespace console { typedef OverloadedCommandNode node_type; typedef OverloadedCommandNode & result_type; - OverloadedCommandNode & create(DirectoryNode & dir, std::string const & name) const; - protected: ParsedCommandAttributorBase(ParsedCommandOverloadBase::ptr overload, unsigned index); ParsedCommandAttributorBase(ParsedCommandAttributorBase const & other, unsigned index); @@ -227,10 +221,14 @@ namespace console { void shortDoc(std::string const & doc); private: + OverloadedCommandNode & create(DirectoryNode & dir, std::string const & name) const; + ParsedCommandOverloadBase::ptr overload_; unsigned index_; boost::optional doc_; boost::optional shortdoc_; + + friend class senf::console::DirectoryNode; }; /** \brief Non argument dependent ParsedCommandBase attributes @@ -577,6 +575,67 @@ namespace console { namespace factory { +#ifdef DOXYGEN + + /** \brief OverloadedCommandNode factory + + This factory will create new OverloadedCommandNode instances or add new overloads + to an existing OverloadedCommandNode. The factory supports automatic argument parsing. + + Commands are added to the tree using + \code + namespace fty = senf::console::factory; + node.add("name", fty::Command(function)); + \endcode + + The Command factory supports the following features: + \li Automatic argument parsing + \li Automatic binding of member functions. Pass the owning instance as second argument to + the factory + \li Conversion to a compatible signature. Pass the signature as template argument to the + factory + + If the signature of the command added matches + \code + void (std::ostream &, senf::console::ParsedCommandInfo const &) + \endcode + The command is added using manual argument parsing, otherwise it is added using automatic + argument parsing. + + See the List of all + members for additional attributes. + + \note This class is for exposition only, the real interface consists of several overloaded + factory functions. + + \see \ref console_manualparse \n + \ref console_autoparse + */ + class Command : public ParsedArgumentAttributor + { + public: + typedef OverloadedCommandNode node_type; + typedef unspecified result_type; + + Command(unspecified fn); ///< Create a node calling \a fn + template + Command(unspecified fn); ///< Create a node calling \a fn with signature \a Signature + /**< The given \a Signature must be compatible with \a fn + for each argument and the return value. */ + + Command(member_function_pointer fn, Owner const * owner); + ///< Create a node calling member function \a fn on \a owner + template + Command(member_function_pointer fn, Owner const * owner); + ///< Create a node calling member function \a fn on \a owner + /// with the given \a Signature + /**< The given \a Signature must be compatible with \a fn + for each argument and the return value. */ + + }; + +#else + template SimpleOverloadAttributor Command(boost::function fn, @@ -639,6 +698,7 @@ namespace factory { Command(Member memfn, Owner const * owner, typename boost::enable_if >::type * = 0); +#endif }}} diff --git a/senf/Utils/Console/Variables.hh b/senf/Utils/Console/Variables.hh index a732b41..ee78fbc 100644 --- a/senf/Utils/Console/Variables.hh +++ b/senf/Utils/Console/Variables.hh @@ -44,10 +44,8 @@ namespace console { namespace factory { - /** \brief Variable command attributes (const) +#ifndef DOXYGEN - \see VariableFactory - */ template class ConstVariableFactory : public detail::NodeFactory @@ -72,7 +70,9 @@ namespace factory { boost::optional shortdoc_; }; - /** \brief Variable command attributes +#endif + + /** \brief Variable node factory Variable commands allow to register any arbitrary variable as a command node. The variable will be registered as two command overloads: One which takes a single argument of the @@ -94,17 +94,24 @@ namespace factory { variable. It is also possible, to register a variable read-only. To achieve this, just wrap it with \c - boost::cref(). Such a variable cannot be changed only queried. Therefore, it does not have - the parser() and typeName() attributes. + boost::cref(). Such a variable only queried. Therefore, it does not have the parser() and + typeName() attributes. \code dir.add("const_var", fty::Variable(boost::cref(var))); \endcode - \ingroup console_commands + \note Even though the interface is documented as a class, in reality it is implemented using + factory functions returning instances of an internal factory class. + + \see \ref console_variables */ +#ifdef DOXYGEN + class Variable +#else template class VariableFactory : public ConstVariableFactory +#endif { public: typedef typename detail::SetVariable::Traits::Overload SetOverload; @@ -147,17 +154,21 @@ namespace factory { void handler(Variable const & oldValue); \endcode */ - OverloadedCommandNode & create(DirectoryNode & dir, std::string const & name) const; - - explicit VariableFactory(Variable & var); + explicit VariableFactory(Variable & var); ///< Create Variable node protected: private: + OverloadedCommandNode & create(DirectoryNode & dir, std::string const & name) const; + typename SetOverload::ptr setOverload_; Variable & var_; + + friend class senf::console::DirectoryNode; }; +#ifndef DOXYGEN + template VariableFactory Variable(Var & var); @@ -170,6 +181,8 @@ namespace factory { template ConstVariableFactory Variable(boost::reference_wrapper var); +#endif + }}} ///////////////////////////////hh.e//////////////////////////////////////// diff --git a/site_scons/lib/doxygen.sh b/site_scons/lib/doxygen.sh index 90abf08..19d6560 100755 --- a/site_scons/lib/doxygen.sh +++ b/site_scons/lib/doxygen.sh @@ -5,6 +5,7 @@ do_html_cleanup() sed -e 's/id="current"/class="current"/' \ | tidy -ascii -q --wrap 0 --show-warnings no --fix-uri no \ | sed -e 's/name="\([^"]*\)"\([^>]*\) id="\1"/name="\1"\2/g' \ + -e 's/id="\([^"]*\)"\([^>]*\) name="\1"/name="\1"\2/g' \ | xsltproc --novalid --nonet --html --stringparam topdir "$reltopdir" \ "$base/html-munge.xsl" - }