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 2017/10/17 18:35:19 UTC
mesos git commit: Updated Doxygen style guide docs to latest
expectations.
Repository: mesos
Updated Branches:
refs/heads/master 982aba2e9 -> e757918f8
Updated Doxygen style guide docs to latest expectations.
In particular, removed the discussion of Markdown files as we no
longer generate Doxygen representations of our Markdown files but
instead link to them in GitHub.
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/e757918f
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/e757918f
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/e757918f
Branch: refs/heads/master
Commit: e757918f849ed2fd0f4cbc05e029f7fade493440
Parents: 982aba2
Author: Benjamin Hindman <be...@gmail.com>
Authored: Tue Oct 17 11:32:49 2017 -0700
Committer: Benjamin Hindman <be...@gmail.com>
Committed: Tue Oct 17 11:32:49 2017 -0700
----------------------------------------------------------------------
docs/doxygen-style-guide.md | 245 ++++++++++++++++++---------------------
1 file changed, 112 insertions(+), 133 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/e757918f/docs/doxygen-style-guide.md
----------------------------------------------------------------------
diff --git a/docs/doxygen-style-guide.md b/docs/doxygen-style-guide.md
index 53a27fe..2dd1b7f 100644
--- a/docs/doxygen-style-guide.md
+++ b/docs/doxygen-style-guide.md
@@ -23,179 +23,158 @@ We follow the [Javadoc syntax](http://en.wikipedia.org/wiki/Javadoc) to mark com
These have the general form:
-<!-- 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.
- */
+```cpp
+/**
+ * Brief summary.
+ *
+ * Detailed description. More detail.
+ * @see Some reference
+ *
+ * @param <name> Parameter description.
+ * @return Return value description.
+ */
+```
Example:
- /**
- * 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);
-
+```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.
- * [\@see](http://doxygen.org/manual/commands.html#cmdsa) Describes a cross-reference to classes, functions, methods, variables, files or URL.
+ * [`@param`](http://doxygen.org/manual/commands.html#cmdparam) Describes function parameters.
+ * [`@return`](http://doxygen.org/manual/commands.html#cmdreturn) Describes return values.
+ * [`@see`](http://doxygen.org/manual/commands.html#cmdsa) Describes a cross-reference to classes, functions, methods, variables, files or URL.
Example:
- /**
- * Available kinds of implementations.
- *
- * @see process::network::PollSocketImpl
- */
+```cpp
+/**
+ * Available kinds of implementations.
+ *
+ * @see process::network::PollSocketImpl
+ */
+```
- * [\@file](http://doxygen.org/manual/commands.html#cmdfile) Describes a refence to a file. It is required when documenting global functions, variables, typedefs, or enums in separate files.
- * [\@link](http://doxygen.org/manual/commands.html#cmdlink) and [\@endlink](http://doxygen.org/manual/commands.html#cmdendlink) Describes a link to a file, class, or member.
- * [\@example](http://doxygen.org/manual/commands.html#cmdexample) Describes source code examples.
- * [\@image](http://doxygen.org/manual/commands.html#cmdimage) Describes an image.
+ * [`@file`](http://doxygen.org/manual/commands.html#cmdfile) Describes a refence to a file. It is required when documenting global functions, variables, typedefs, or enums in separate files.
+ * [`@link`](http://doxygen.org/manual/commands.html#cmdlink) and [`@endlink`](http://doxygen.org/manual/commands.html#cmdendlink) Describes a link to a file, class, or member.
+ * [`@example`](http://doxygen.org/manual/commands.html#cmdexample) Describes source code examples.
+ * [`@image`](http://doxygen.org/manual/commands.html#cmdimage) Describes an image.
- * When following these links be aware that the doxygen documentation is using another syntax in that \@param is explained as \\param.
+> When following these links be aware that the Doxygen documentation uses the `\param` syntax rather than `@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
- description on this line as well.
+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.
+ */
+```
### Constants and Variables
Example:
- /**
- * 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;
-
+```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;
+```
#### Fields
Example:
- /**
- * 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;
-
+```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;
+```
### Functions and Methods
Example:
- /**
- * 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());
-
+```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());
+```
### Classes and Structs
Example:
- /**
- * 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
-
-Substantial libraries, components, and subcomponents of the Mesos system such as
-stout, libprocess, master, agent, 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.
-
-This page must be located in the top directory of the library/component and named "README.md".
-
-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"
-
-### Example Code
-
-C++ code examples should be enclosed by '~~~{.cpp}'.
-
-Example:
-
-~~~{.cpp}
-int main(int argc, char** argv)
+```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
{
- ...
-}
-~~~
-
-**NOTE**: Because of shortcomings of Doxygen's markdown parser we currently use indentation for wrapping all non C++ code blocks.
+public:
+```
## 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.
+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.