You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by be...@apache.org on 2015/06/25 17:28:31 UTC
mesos git commit: Fixed bad review cleanup in doxygen style guide.
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 <be...@gmail.com>
Authored: Thu Jun 25 08:28:27 2015 -0700
Committer: Benjamin Hindman <be...@gmail.com>
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