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/23 12:44:16 UTC
mesos git commit: Doxygen Style Guide Improvements.
Repository: mesos
Updated Branches:
refs/heads/master 54ca19e00 -> fc533857e
Doxygen Style Guide Improvements.
Added style examples and improved structure.
Review: https://reviews.apache.org/r/35509
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/fc533857
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/fc533857
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/fc533857
Branch: refs/heads/master
Commit: fc533857e3ff4cddc183fee4e65cde40132ea624
Parents: 54ca19e
Author: Joerg Schad <jo...@mesosphere.io>
Authored: Tue Jun 23 12:43:50 2015 +0200
Committer: Bernd Mathiske <be...@mesosphere.io>
Committed: Tue Jun 23 12:43:50 2015 +0200
----------------------------------------------------------------------
docs/mesos-doxygen-style-guide.md | 193 +++++++++++++++++++++++----------
1 file changed, 133 insertions(+), 60 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/fc533857/docs/mesos-doxygen-style-guide.md
----------------------------------------------------------------------
diff --git a/docs/mesos-doxygen-style-guide.md b/docs/mesos-doxygen-style-guide.md
index 0ac3837..93a5e70 100644
--- a/docs/mesos-doxygen-style-guide.md
+++ b/docs/mesos-doxygen-style-guide.md
@@ -6,20 +6,47 @@ using [Doxygen](http://www.doxygen.org).
There is an ongoing, incremental effort with the goal to document all public Mesos, libprocess, and stout APIs this way.
For now, existing code may not follow these guidelines, but new code should.
-## Preliminaries
-We follow the [IETF RFC2119](https://www.ietf.org/rfc/rfc2119.txt)
-on how to use words such as "must", "should", "can",
-and other requirement-related notions.
+## Source Code Documentation Syntax
+Doxygen documentation needs only to be applied to source code parts that
+constitute an interface for which we want to generate Mesos API documentation
+files. Implementation code that does not participate in this should still be
+enhanced by source code comments as appropriate, but these comments should not follow the doxygen style.
-## Building Doxygen Documentation
-As of right now, the Doxygen documentation should be built from the *build* subdirectory using *doxygen ../Doxyfile* . The documentation will then be generated into the *./doxygen* subdirectory.
-Todo: We should create a regular make target.
+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.
+ */
+~~~
-## Doxygen Tags
-*When following these links be aware that the doxygen documentation is using another syntax in that @param is explained as \param.*
+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);
+~~~
+
+
+### Doxygen Tags
+
+This is the allowed set of doxygen tags that can be used.
* [@param](http://doxygen.org/manual/commands.html#cmdparam) Describes function parameters.
* [@return](http://doxygen.org/manual/commands.html#cmdreturn) Describes return values.
@@ -30,8 +57,13 @@ Todo: We should create a regular make target.
* [@todo](http://doxygen.org/manual/commands.html#cmdtodo) Describes a TODO item.
* [@image](http://doxygen.org/manual/commands.html#cmdimage) Describes an image.
-## Wrapping
-We wrap long descriptions using 4 spaces on the next line.
+*When following these links be aware that the doxygen documentation is using another syntax in that @param is explained as \param.*
+
+
+### Wrapping
+
+We wrap long descriptions using four spaces on the next line.
+
~~~
@param uncompressed The input string that requires
a very long description and an even longer
@@ -39,82 +71,123 @@ We wrap long descriptions using 4 spaces on the next line.
~~~
-## Outside Source Code
-
-### Library and Component Overview Pages and User Guides
-
-Substantial libraries, components, and subcomponents of the Mesos system such as
-stout, libprocess, master, slave, containerizer, allocator, and others
-should have an overview page in markdown format that explains their
-purpose, overall structure, and general use. This can even be a complete user guide.
-
-This page must be located in the top directory of the library/component and named "REAMDE.md".
+### Constants and Variables
-The first line in such a document must be a section heading bearing the title which will appear in the generated Doxygen index.
-Example: "# Libprocess User Guide"
+Example:
-#### Example Code
+~~~{.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;
+~~~
-Code examples must be enclosed by '~~~{.Language}'
+#### Fields
Example:
-~~~
- ~~~{.cpp}
- int main(int argc, char** argv)
- {
- ....
- }
- ~~~
+
+~~~{.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;
~~~
-## In Source Code
-Doxygen documentation needs only to be applied to source code parts that
-constitute an interface for which we want to generate Mesos API documentation
-files. Implementation code that does not participate in this should still be
-enhanced by source code comments as appropriate, but these comments should not follow the doxygen style.
+### Functions and Methods
-We follow the [Javadoc syntax](http://en.wikipedia.org/wiki/Javadoc) to mark comment blocks.
-These have the general form:
+Example:
~~~{.cpp}
/**
- * Brief summary.
+ * 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.
*
- * Detailed description. More detail.
- * @see Some reference
+ * 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 <name> Parameter description.
- * @return Return value description.
+ * @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 add or overwrite
+ * existing environment variables.
+ * @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}
/**
- * 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);
+* 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
~~~
-### Constants and Variables
-### Functions
+## Library and Component Overview Pages and Developer Guides
+
+Substantial libraries, components, and subcomponents of the Mesos system such as
+stout, libprocess, master, slave, containerizer, allocator, and others
+should have an overview page in markdown format that explains their
+purpose, overall structure, and general use. This can even be a complete developer guide.
-### Classes
+This page must be located in the top directory of the library/component and named "REAMDE.md".
-#### Methods
+The first line in such a document must be a section heading bearing the title which will appear in the generated Doxygen index.
+Example: "# Libprocess Developer Guide"
-#### Fields
-### Templates
+### Example Code
+
+Code examples must be enclosed by '~~~{.Language}'
+
+
+Example:
+~~~{.text}
+ ~~~{.cpp}
+ int main(int argc, char** argv)
+ {
+ ....
+ }
+ ~~~
+~~~
-### Macros
-### Global declarations outside classes
+## Building Doxygen Documentation
+
+As of right now, the Doxygen documentation should be built from the *build* subdirectory using *doxygen ../Doxyfile* . The documentation will then be generated into the *./doxygen* subdirectory.