[SCM] Samba Shared Repository - branch master updated

[Stefan Metzmacher]

The branch, master has been updated
       via  1c2ff45... README.Coding: add examples for good and bad comments
      from  23f8100... s4:provision: remove --policy-guid and --policy-guid-dc cmdline options

http://gitweb.samba.org/?p=samba.git;a=shortlog;h=master


- Log -----------------------------------------------------------------
commit 1c2ff4563d0fd7e1d00117eef051f5554daaba14
Author: Stefan Metzmacher <metze at samba.org>
Date:   Sat Jul 10 10:06:17 2010 +0200

    README.Coding: add examples for good and bad comments
    
    metze

-----------------------------------------------------------------------

Summary of changes:
 README.Coding |   75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 73 insertions(+), 2 deletions(-)


Changeset truncated at 500 lines:

diff --git a/README.Coding b/README.Coding
index ba70a3c..b1ac2fe 100644
--- a/README.Coding
+++ b/README.Coding
@@ -94,8 +94,79 @@ Comments
 --------
 
 Comments should always use the standard C syntax.  C++
-style comments are not currently allowed.
+style comments are not currently allowed. The lines before
+a comment should be empty. If the comment directly belongs
+to the following code, there should be no empty line after
+the comment. In case the comment contains a summary of
+mutliple following code blogs.
 
+This is good:
+
+	...
+	int i;
+
+	/*
+	 * This is a multi line comment,
+	 * which explains the logical steps we have to do:
+	 *
+	 * 1. We need to set i=5, because...
+	 * 2. We need to call complex_fn1
+	 */
+
+	/* This is a one line comment about i = 5. */
+	i = 5;
+
+	/*
+	 * This is a multi line comment,
+	 * explaining the call to complex_fn1()
+	 */
+	ret = complex_fn1();
+	if (ret != 0) {
+	...
+
+	/**
+	 * @brief This is a doxygen comment.
+	 *
+	 * This is a more detailed explanation of
+	 * this simple function.
+	 *
+	 * @param[in]   param1     The parameter value of the function.
+	 *
+	 * @param[out]  result1    The result value of the function.
+	 *
+	 * @return              0 on success and -1 on error.
+	 */
+	int example(int param1, int *result1);
+
+This is bad:
+
+	...
+	int i;
+	/*
+	 * This is a multi line comment,
+	 * which explains the logical steps we have to do:
+	 *
+	 * 1. We need to set i=5, because...
+	 * 2. We need to call complex_fn1
+	 */
+	/* This is a one line comment about i = 5. */
+	i = 5;
+	/*
+	 * This is a multi line comment,
+	 * explaining the call to complex_fn1()
+	 */
+	ret = complex_fn1();
+	if (ret != 0) {
+	...
+
+	/*This is a one line comment.*/
+
+	/* This is a multi line comment,
+	   with some more words...*/
+
+	/*
+	 * This is a multi line comment,
+	 * with some more words...*/
 
 Indention & Whitespace & 80 columns
 -----------------------------------


-- 
Samba Shared Repository