Repository: incubator-rocketmq-site Updated Branches: refs/heads/master 4f9cb7d3d -> 17eacba33
Add documentation guideline. Project: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/commit/17eacba3 Tree: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/tree/17eacba3 Diff: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/diff/17eacba3 Branch: refs/heads/master Commit: 17eacba332c93fa5601d56b89dfba23a4ffc93b0 Parents: 4f9cb7d Author: Zhanhui Li <[email protected]> Authored: Wed Mar 1 16:27:20 2017 +0800 Committer: Zhanhui Li <[email protected]> Committed: Wed Mar 1 16:27:20 2017 +0800 ---------------------------------------------------------------------- _docs/07-code-guidelines.md | 2 +- _docs/07-documentation.md | 57 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/17eacba3/_docs/07-code-guidelines.md ---------------------------------------------------------------------- diff --git a/_docs/07-code-guidelines.md b/_docs/07-code-guidelines.md index 5f0e784..3326140 100644 --- a/_docs/07-code-guidelines.md +++ b/_docs/07-code-guidelines.md @@ -10,7 +10,7 @@ modified: 2016-12-29T15:01:43-04:00 # Introduction This document describes formatting rules and guidelines for software source code. Note that this document does not cover best programming practices or techniques. It is solely concentrating on source code formatting and conventions. -Studies have shown that 80% of development time spent on software maintenance which involves software source code understanding, refactoring and support. Established and enforced code formatting rules and guidelines improve source code readability, promote team code ownership, allow engineers understand new code more quickly and thorough as well as simplify maintenance. +Studies have shown that 80% of development time is spent on software maintenance which involves software source code understanding, refactoring and support. Established and enforced code formatting rules and guidelines improve source code readability, promote team code ownership, allow engineers understand new code more quickly and thorough as well as simplify maintenance. # Code template for idea ## Import code style http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/17eacba3/_docs/07-documentation.md ---------------------------------------------------------------------- diff --git a/_docs/07-documentation.md b/_docs/07-documentation.md new file mode 100644 index 0000000..7aa5bc3 --- /dev/null +++ b/_docs/07-documentation.md @@ -0,0 +1,57 @@ +--- +title: "Documentation" +permalink: /docs/documentation/ +excerpt: "Apache RocketMQ Documentation" +modified: 2017-03-01T15:01:43-04:00 +--- + +{% include toc %} + +# Introduction + +Quality documentation is critically important to develop and maintain a project. The better the documentation is, the +easier it will be for other participants to understand and respond properly. + +## API Documentation + +The API is documented through javadoc comments. + +All classes, interfaces, methods and field variables should be documented. Public methods, in particular, should be +commented fully -- method purpose, return value, parameters and exceptions. + +Below is an example: + + /** + * Send message in synchronous mode. This method returns only when the sending procedure totally completes. + * </p> + * + * <strong>Warn:</strong> this method has internal retry-mechanism, that is, internal implementation will retry + * {@link #retryTimesWhenSendFailed} times before claiming failure. As a result, multiple messages may potentially + * delivered to broker(s). It's up to the application developers to resolve potential duplication issue. + * + * @param msg Message to send. + * @return {@link SendResult} instance to inform senders details of the deliverable, say Message ID of the message, + * {@link SendStatus} indicating broker storage/replication status, message queue sent to, etc. + * @throws MQClientException if there is any client error. + * @throws RemotingException if there is any network-tier error. + * @throws MQBrokerException if there is any error with broker. + * @throws InterruptedException if the sending thread is interrupted. + */ + @Override + public SendResult send(Message msg) throws MQClientException, RemotingException, MQBrokerException, InterruptedException { + return this.defaultMQProducerImpl.send(msg); + } + + +## Documentation Content + +Every class and interface should have summary documentation, explaining its general function and purpose. Additionally, +thread safety information should be included. If you are working on a class which represents a core concept, adding sample +usage is always a good practice. + + +When writing API documentation, please keep a professional tune: write in active voice, be as descriptive as possible. +Keep in mind that the audience may be a developer who would use RocketMQ for the first time, or a contributor who just gets + involved with the codebase. Either of them is not as familiar with Apache RocketMQ as you are. + +
