wip torture: Add doxygen comments for smb2.rename

diff --git a/source4/torture/smb2/rename.c b/source4/torture/smb2/rename.c
index 23fe4f9494fe463f998808c5dbe6fc1aeea7b631..6ced4f9d97cfc96cacc147c4bb42a7e04f1e8230 100755 (executable)
--- a/source4/torture/smb2/rename.c
+++ b/source4/torture/smb2/rename.c
@@ -41,11 +41,23 @@
 
 #define BASEDIR "test_rename"
 
-/*
- * basic testing of rename: open file with DELETE access
- * this should pass
+/**
+ * Testcase smb2.rename.simple
+ *
+ * Basic testing of rename: open file with DELETE access. This should
+ * pass.
+ *
+ * - Create base directory
+ * - Create test file with DELETE access
+ * - Rename testfile
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_simple(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -130,11 +142,24 @@ done:
        return ret;
 }
 
-/*
- * basic testing of rename, this time do not request DELETE access
- * for the file, this should fail
+/**
+ * Testcase smb2.rename.simple2
+ *
+ * Basic testing of rename, this time do not request DELETE access
+ * for the file, this should fail.
+ *
+ * - Create base directory
+ * - Create test file without DELETE access
+ * - Rename test file
+ * - Expect ACCESS_DENIED
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_simple2(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -210,11 +235,22 @@ done:
 }
 
 
-/*
- * testing of rename with no sharing allowed on file
- * this should work
+/**
+ * Testcase smb2.rename_nosharing
+ *
+ * Testing of rename with no sharing allowed on file. This should work.
+ *
+ * - Create base directory
+ * - Create test file with exclusive access.
+ * - Rename test file
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_no_sharemode(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -298,12 +334,25 @@ done:
        return ret;
 }
 
-/*
- * testing of rename when opening parent dir with delete access and delete
- * sharing allowed
- * should result in sharing violation
+/**
+ * Testcase smb2.rename.share_delete_and_delete_access
+ *
+ * Testing of rename when opening parent dir with delete access and
+ * delete sharing allowed should result in sharing violation.
+ *
+ * - Create base directory
+ * - Open base directory with delete access and delete sharing
+ * - Create file
+ * - Rename file
+ * - Expect SHARING_VIOLATION
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_with_delete_access(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -423,12 +472,20 @@ done:
 }
 
 
-/*
- * testing of rename with delete access on parent dir
- * this is a variation of the test above: parent dir is opened
- * without share_delete, so rename must fail
+/**
+ * Testcase smb2.rename.no_share_delete_but_delete_access
+ *
+ * Testing of rename with delete access on parent dir. This is a
+ * variation of the test above: parent dir is opened without
+ * share_delete, so rename must fail.
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_with_delete_access2(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -546,12 +603,19 @@ done:
        return ret;
 }
 
-/*
- * testing of rename when opening parent dir with no delete access and delete
- * sharing allowed
- * this should pass
+/**
+ * Testcase smb2.rename.share_delete_no_delete_access
+ *
+ * Testing of rename when opening parent dir with no delete access and delete
+ * sharing allowed. This should pass.
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_no_delete_access(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -681,12 +745,20 @@ done:
 }
 
 
-/*
- * testing of rename with no delete access on parent dir
- * this is the negative case of the test above: parent dir is opened
- * without share_delete, so rename must fail
+/**
+ * Testcase smb2.rename.no_share_delete_no_delete_access
+ *
+ * Testing of rename with no delete access on parent dir.  This is the
+ * negative case of the test above: Parent dir is opened without
+ * share_delete, so rename must fail.
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_no_delete_access2(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -804,11 +876,18 @@ done:
        return ret;
 }
 
-/*
- * this is a replay of how Word 2010 saves a file
- * this should pass
+/**
+ * Testcase smb2.rename.msword
+ *
+ * This is a replay of how Word 2010 saves a file this should pass.
+ *
+ * @ingroup smb2_rename
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
  */
-
 static bool torture_smb2_rename_msword(struct torture_context *torture,
                struct smb2_tree *tree1)
 {
@@ -928,6 +1007,17 @@ done:
        return ret;
 }
 
+/**
+ * Testcase smb2.rename.rename_dir_openfile
+ *
+ * Test renaming directory while file in directory is open. This
+ * should fail.
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
+ */
 static bool torture_smb2_rename_dir_openfile(struct torture_context *torture,
                                             struct smb2_tree *tree1)
 {
@@ -1368,6 +1458,18 @@ static NTSTATUS rename_dirs_bench_recv(struct tevent_req *req)
        return tevent_req_simple_recv_ntstatus(req);
 }
 
+/**
+ * Testcase smb2.rename.rename_dir_bench
+ *
+ * This is a little benchmark test excercising parallel directory
+ * renames. With lots of open files directory renames get pretty slow
+ * against some SMB server implementations.
+ *
+ * @param torture torture context
+ * @param tree1 SMB2 tree context
+ *
+ * @return boolean Returns true if test succeeded, false if not.
+ */
 static bool torture_smb2_rename_dir_bench(struct torture_context *tctx,
                                          struct smb2_tree *tree)
 {
@@ -1392,8 +1494,10 @@ static bool torture_smb2_rename_dir_bench(struct torture_context *tctx,
 }
 
 
-/*
-   basic testing of SMB2 rename
+/**
+ * @defgroup smb2_rename smb2.rename
+ *
+ * Basic testing of SMB2 rename
  */
 struct torture_suite *torture_smb2_rename_init(void)
 {