From 588e144a1efc876cc5c4624a4b112f3e20fda266 Mon Sep 17 00:00:00 2001 From: Christos Houtouridis Date: Mon, 18 Feb 2019 18:46:43 +0200 Subject: [PATCH] Some comment work for doxygen --- Doxyfile | 8 +++--- README.html | 1 + src/Snel.cpp | 23 ++++++++++++++++- src/sequencer.cpp | 11 +++++---- src/sequencer.h | 63 +++++++++++++++++++++++------------------------ 5 files changed, 64 insertions(+), 42 deletions(-) create mode 120000 README.html diff --git a/Doxyfile b/Doxyfile index 2400e11..36ff4d9 100644 --- a/Doxyfile +++ b/Doxyfile @@ -441,7 +441,7 @@ EXTRACT_ALL = NO # be included in the documentation. # The default value is: NO. -EXTRACT_PRIVATE = NO +EXTRACT_PRIVATE = YES # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. @@ -453,7 +453,7 @@ EXTRACT_PACKAGE = NO # included in the documentation. # The default value is: NO. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, @@ -469,7 +469,7 @@ EXTRACT_LOCAL_CLASSES = YES # included. # The default value is: NO. -EXTRACT_LOCAL_METHODS = NO +EXTRACT_LOCAL_METHODS = YES # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called @@ -2214,7 +2214,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: YES. -HAVE_DOT = YES +HAVE_DOT = NO # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of diff --git a/README.html b/README.html new file mode 120000 index 0000000..fad8790 --- /dev/null +++ b/README.html @@ -0,0 +1 @@ +doc/html/index.html \ No newline at end of file diff --git a/src/Snel.cpp b/src/Snel.cpp index caf5c1c..e787997 100755 --- a/src/Snel.cpp +++ b/src/Snel.cpp @@ -5,11 +5,32 @@ * * Created on: Feb, 2019 * Author: Christos Choutouridis AEM: 8997 - * email : cchoutou@ece.auth.gr + * email : */ #include "sequencer.h" +/*! + * \mainpage + * Snel is a shell implementation for A.U.TH (Operating systems Lab). + * The shell execute the user commands in separate child processes. + * + * It supports: + * * Interactive mode + * * Batch mode + * * # line comments + * * std redirection + * * &&, || operators and ; seperator + * * pipes + * + * The implementation is based on a 2 dimensional sequencer. One dimension + * is the command chains, namely the commands separated with ';' and the other + * is the chains (the commands to run as one expression like ls && date). + * For more information look at \see Sequencer. + */ +/*! + * Main program routine + */ int main(int argc, char* argv[]) try { snel::Sequencer seq{}; std::string line, filtered; diff --git a/src/sequencer.cpp b/src/sequencer.cpp index 47ee6df..b8d66a9 100755 --- a/src/sequencer.cpp +++ b/src/sequencer.cpp @@ -5,7 +5,7 @@ * * Created on: Feb, 2019 * Author: Christos Choutouridis AEM: 8997 - * email : cchoutou@ece.auth.gr + * email : */ #include "sequencer.h" @@ -209,14 +209,15 @@ namespace snel { /*! * \brief Execute the child in separate process. * - * This is the hart of the snel. We use fork() - execvp() pair to execute + * This is the hart of the snel. We use fork() - execvp() pair to execute * each child. In case of std redirection, the fd/dup2 handling is made in the - * parent. In case of piping. The fd handling is made in parent and the + * parent. In case of piping, the fd handling is made in parent and the * dup2() calls in the child process. * * A child is a member of a vector containing the command chain. - * For ex: `ls && cat tralala || uname -a` is a chain with three - * childs (ls, cat, uname). See also \see Sequencer + * For ex: + * \code ls && cat tralala || uname -a \endcode + * is a chain with three childs (ls, cat, uname). \see Sequencer * * \param it Iterator to the command chain execution * \param first flag to indicate the first command in the chain diff --git a/src/sequencer.h b/src/sequencer.h index 5056aec..964039a 100755 --- a/src/sequencer.h +++ b/src/sequencer.h @@ -5,7 +5,7 @@ * * Created on: Feb, 2019 * Author: Christos Choutouridis AEM: 8997 - * email : cchoutou@ece.auth.gr + * email : */ #ifndef __sequencer_h__ #define __sequencer_h__ @@ -29,32 +29,30 @@ namespace snel { //! file descriptor type using fd_t = int; - constexpr fd_t STDIN_ = STDIN_FILENO; - constexpr fd_t STDOUT_ = STDOUT_FILENO; - constexpr fd_t STDERR_ = STDERR_FILENO; + constexpr fd_t STDIN_ = STDIN_FILENO; //!< Constant for stdin file descriptor + constexpr fd_t STDOUT_ = STDOUT_FILENO; //!< Constant for stdout file descriptor + constexpr fd_t STDERR_ = STDERR_FILENO; //!< Constant for stderr file descriptor std::string filter (const std::string in); /*! - * A vector based wrapper above execvp()'s `char* argv[]` interface. + * A vector based wrapper above execvp()'s char* argv[] interface. * We use a vector for convenience and resizing capabilities. We can then * use a pointer to underling data to pass to execvp() - * std::vector elements guaranteed to be contiguous. To quote the standard[1] - * \code + * std::vector elements guaranteed to be contiguous. To quote the + * [standard](www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3690.pdf) + * 
     *    The elements of a vector are stored contiguously, meaning that if v is
     *    a vector where T is some type other than bool, then it obeys
     *    the identity &v[n] == &v[0] + n for all 0 <= n < v.size().
-    * \endcode
-    *
-    * See also cppreference[2].
+    *
* - * [1]: www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3690.pdf - * [2]: https://en.cppreference.com/w/cpp/container/vector + * See also [cppreference](https://en.cppreference.com/w/cpp/container/vector) */ struct ArgList { - using type = typename std::string::value_type; // Basic data type (aka char) - using vtype = type*; // Vector type - using vtype_ptr = vtype*; // Pointer to vector type + using type = typename std::string::value_type; //!< Basic data type (aka char) + using vtype = type*; //!< Vector type + using vtype_ptr = vtype*; //!< Pointer to vector type ~ArgList(); ArgList() = default; @@ -65,12 +63,12 @@ namespace snel { vtype front () { return args_.front(); } //!< A vector::front() wrapper size_t size () { return args_.size(); } //!< A vector::size() wrapper - //! return a pointer to underling data for `execvp()` + //! return a pointer to underling data for \c execvp() vtype_ptr data() noexcept { return args_.data(); } - //! same as `data()` + //! same as \c data() vtype_ptr operator*() noexcept { return data(); } private: - // data + //! underling data for the \c execvp() arguments std::vector args_ {nullptr}; }; @@ -78,8 +76,8 @@ namespace snel { /*! * A pipe file descriptor container for each child. * \note - * We store the pipe in the first child and use the flags `from` - * and `to` to inform child's executer for where can find the data. + * We store the pipe in the first child and use the flags \c from + * and \c to to inform child's executer for where can find the data. */ struct Pipe { ~Pipe(); @@ -91,13 +89,15 @@ namespace snel { /*! * An object to represent each process * - * We create Child objects from command_t passed from Sequence::parse() and we - * keep in each child informations about the file descriptors that may the process - * will use, pipes that may need and logic flags(&&, ||) the command may have to control - * the execution flow. + * We create Child objects from \c command_t passed to constructor from \c Sequence::parse(). + * In child we store information about: + * * The file descriptors for std redirection the process may use + * * Pipes that may needed for communication with the \b next child + * * Logic flags \c (&&, ||) the command may have, to control the execution flow. */ class Child { public: + //! Enumerator for the logic operators between commands enum class LogicOp { NONE=0, OR, AND }; @@ -111,20 +111,19 @@ namespace snel { Child (command_t&& c) : command{std::move(c)} { } Child& make_arguments (); //!< A per child parser before execution - //! the actual execution routine bool execute(std::vector::iterator it, bool first); Pipe& pipe() { return pipe_; } //!< A pipe_ getter //! Private api //! @{ private: - void redirect_std_if(std::string fn, fd_t std_fd); //!< tool to redirect std - void restore_std_if(fd_t std_fd); //!< tool to restor std redirection + void redirect_std_if(std::string fn, fd_t std_fd); //!< Tool to redirect std + void restore_std_if(fd_t std_fd); //!< Tool to restore std redirection //! @} //! Data members //! \note - //! `arguments`, `files`, `sstd` and `pipe_` have linked resources so destructor(s) must be called. + //! \c arguments, \c files, \c sstd and \c pipe_ have linked resources so destructor(s) must be called. //! We use RAII by having all children to static allocated vectors. '}' will do the trick even //! if we throw ;) //! @{ @@ -155,13 +154,13 @@ namespace snel { * \endcode * By storing them in different vector we make the execution model simpler. * Each chain can stopped and the sequencer will continue with the next chain etc... - * So in this example if `more` returns false(child::execute() returned true), - * then `uname` will not parsed and executed and the flow will continue to `cat` + * So in this example if \c more returns false(child::execute() returned true), + * then \c uname will not parsed and executed and the flow will continue to \c cat */ class Sequencer { public: - Sequencer& parse (const std::string& input); //!< Input line parser - Sequencer& execute (); //!< Main sequencer executor + Sequencer& parse (const std::string& input); + Sequencer& execute (); //! private tools //! @{