Repository: mesos Updated Branches: refs/heads/master b0823c20b -> 4bb0f21eb
Fixed bad review cleanup in doxygen style guide. Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/4bb0f21e Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/4bb0f21e Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/4bb0f21e Branch: refs/heads/master Commit: 4bb0f21eb89f310e9b1255d5536d7141744600fc Parents: b0823c2 Author: Benjamin Hindman <[email protected]> Authored: Thu Jun 25 08:28:27 2015 -0700 Committer: Benjamin Hindman <[email protected]> Committed: Thu Jun 25 08:28:27 2015 -0700 ---------------------------------------------------------------------- docs/mesos-doxygen-style-guide.md | 181 ++++++++++++++++----------------- 1 file changed, 87 insertions(+), 94 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/4bb0f21e/docs/mesos-doxygen-style-guide.md ---------------------------------------------------------------------- diff --git a/docs/mesos-doxygen-style-guide.md b/docs/mesos-doxygen-style-guide.md index be9b012..72156c7 100644 --- a/docs/mesos-doxygen-style-guide.md +++ b/docs/mesos-doxygen-style-guide.md @@ -17,31 +17,34 @@ enhanced by source code comments as appropriate, but these comments should not f We follow the [Javadoc syntax](http://en.wikipedia.org/wiki/Javadoc) to mark comment blocks. These have the general form: -~~~{.cpp} -/** - * Brief summary. - * - * Detailed description. More detail. - * @see Some reference - * - * @param <name> Parameter description. - * @return Return value description. - */ -~~~ + +<!-- NOTE: In order to show the comments as part of the code blocks in +this we must use indentation instead of fenced code blocks (i.e., +~~~{.cpp}) because doxygen will remove all of the comments and just +render the code. --> + + + /** + * Brief summary. + * + * Detailed description. More detail. + * @see Some reference + * + * @param <name> Parameter description. + * @return Return value description. + */ Example: -~~~{.cpp} -/** - * Returns a compressed version of a string. - * - * Compresses an input string using the foobar algorithm. - * - * @param uncompressed The input string. - * @return A compressed version of the input string. - */ - std::string compress(const std::string& uncompressed); -~~~ + /** + * Returns a compressed version of a string. + * + * Compresses an input string using the foobar algorithm. + * + * @param uncompressed The input string. + * @return A compressed version of the input string. + */ + std::string compress(const std::string& uncompressed); ### Doxygen Tags @@ -64,102 +67,92 @@ This is the allowed set of doxygen tags that can be used. We wrap long descriptions using four spaces on the next line. -~~~{.cpp} -@param uncompressed The input string that requires - a very long description and an even longer - description on this line as well. -~~~ + @param uncompressed The input string that requires + a very long description and an even longer + description on this line as well. ### Constants and Variables Example: -~~~{.cpp} -/** - * Prefix used to name Docker containers in order to distinguish - * those created by Mesos from those created manually. - */ -extern const std::string DOCKER_NAME_PREFIX; -~~~ + /** + * Prefix used to name Docker containers in order to distinguish + * those created by Mesos from those created manually. + */ + extern const std::string DOCKER_NAME_PREFIX; #### Fields Example: -~~~{.cpp} -/** - * The parent side of the pipe for stdin. - * If the mode is not PIPE, None will be stored. - * @note: stdin is a macro on some systems, hence this name instead. - */ -Option<int> in; -~~~ + /** + * The parent side of the pipe for stdin. + * If the mode is not PIPE, None will be stored. + * @note: stdin is a macro on some systems, hence this name instead. + */ + Option<int> in; ### Functions and Methods Example: -~~~{.cpp} -/** - * Forks a subprocess and execs the specified 'path' with the - * specified 'argv', redirecting stdin, stdout, and stderr as - * specified by 'in', 'out', and 'err' respectively. - * - * If 'setup' is not None, runs the specified function after forking - * but before exec'ing. If the return value of 'setup' is non-zero - * then that gets returned in 'status()' and we will not exec. - * - * @param path Relative or absolute path in the filesytem to the - * executable. - * @param argv Argument vector to pass to exec. - * @param in Redirection specification for stdin. - * @param out Redirection specification for stdout. - * @param err Redirection specification for stderr. - * @param flags Flags to be stringified and appended to 'argv'. - * @param environment Environment variables to use for the new - * subprocess or if None (the default) then the new subprocess - * will inherit the environment of the current process. - * @param setup Function to be invoked after forking but before - * exec'ing. NOTE: Take extra care not to invoke any - * async unsafe code in the body of this function. - * @param clone Function to be invoked in order to fork/clone the - * subprocess. - * @return The subprocess or an error if one occurred. - */ -Try<Subprocess> subprocess( - const std::string& path, - std::vector<std::string> argv, - const Subprocess::IO& in = Subprocess::FD(STDIN_FILENO), - const Subprocess::IO& out = Subprocess::FD(STDOUT_FILENO), - const Subprocess::IO& err = Subprocess::FD(STDERR_FILENO), - const Option<flags::FlagsBase>& flags = None(), - const Option<std::map<std::string, std::string>>& environment = None(), - const Option<lambda::function<int()>>& setup = None(), - const Option<lambda::function< - pid_t(const lambda::function<int()>&)>>& clone = None()); -~~~ + /** + * Forks a subprocess and execs the specified 'path' with the + * specified 'argv', redirecting stdin, stdout, and stderr as + * specified by 'in', 'out', and 'err' respectively. + * + * If 'setup' is not None, runs the specified function after forking + * but before exec'ing. If the return value of 'setup' is non-zero + * then that gets returned in 'status()' and we will not exec. + * + * @param path Relative or absolute path in the filesytem to the + * executable. + * @param argv Argument vector to pass to exec. + * @param in Redirection specification for stdin. + * @param out Redirection specification for stdout. + * @param err Redirection specification for stderr. + * @param flags Flags to be stringified and appended to 'argv'. + * @param environment Environment variables to use for the new + * subprocess or if None (the default) then the new subprocess + * will inherit the environment of the current process. + * @param setup Function to be invoked after forking but before + * exec'ing. NOTE: Take extra care not to invoke any + * async unsafe code in the body of this function. + * @param clone Function to be invoked in order to fork/clone the + * subprocess. + * @return The subprocess or an error if one occurred. + */ + Try<Subprocess> subprocess( + const std::string& path, + std::vector<std::string> argv, + const Subprocess::IO& in = Subprocess::FD(STDIN_FILENO), + const Subprocess::IO& out = Subprocess::FD(STDOUT_FILENO), + const Subprocess::IO& err = Subprocess::FD(STDERR_FILENO), + const Option<flags::FlagsBase>& flags = None(), + const Option<std::map<std::string, std::string>>& environment = None(), + const Option<lambda::function<int()>>& setup = None(), + const Option<lambda::function< + pid_t(const lambda::function<int()>&)>>& clone = None()); ### Classes and Structs Example: -~~~{.cpp} -/** - * Represents a fork() exec()ed subprocess. Access is provided to the - * input / output of the process, as well as the exit status. The - * input / output file descriptors are only closed after: - * 1. The subprocess has terminated. - * 2. There are no longer any references to the associated - * Subprocess object. - */ -class Subprocess -{ -public: -~~~ + /** + * Represents a fork() exec()ed subprocess. Access is provided to the + * input / output of the process, as well as the exit status. The + * input / output file descriptors are only closed after: + * 1. The subprocess has terminated. + * 2. There are no longer any references to the associated + * Subprocess object. + */ + class Subprocess + { + public: ## Library and Component Overview Pages and Developer Guides
