From d40454d9c20a9ff70c21aebbbdced277f57e14c2 Mon Sep 17 00:00:00 2001
From: David Wells <wellsd2@rpi.edu>
Date: Sun, 24 Jan 2016 21:44:30 -0500
Subject: [PATCH] Document the line continuation tests.

---
 tests/bits/parameter_handler_backslash_01.cc | 10 ++++++++++
 tests/bits/parameter_handler_backslash_02.cc | 12 ++++++++++++
 tests/bits/parameter_handler_backslash_03.cc |  8 ++++++++
 tests/bits/parameter_handler_backslash_04.cc |  6 ++++++
 tests/bits/parameter_handler_backslash_05.cc | 11 +++++++++++
 tests/bits/parameter_handler_backslash_06.cc |  5 +++++
 tests/bits/parameter_handler_backslash_07.cc | 12 ++++++++++++
 7 files changed, 64 insertions(+)

diff --git a/tests/bits/parameter_handler_backslash_01.cc b/tests/bits/parameter_handler_backslash_01.cc
index 88f65430a4..d0496c713e 100644
--- a/tests/bits/parameter_handler_backslash_01.cc
+++ b/tests/bits/parameter_handler_backslash_01.cc
@@ -19,6 +19,16 @@
 #include <deal.II/base/parameter_handler.h>
 #include <fstream>
 
+/*
+ * Test that ParameterHandler can read parameters of the form
+ *
+ *     set Function = a, \
+ *                    b, \
+ *                    c
+ *
+ * correctly. The main point of this test is to exercise the
+ * backslash-handling part of ParameterHandler.
+ */
 
 int main ()
 {
diff --git a/tests/bits/parameter_handler_backslash_02.cc b/tests/bits/parameter_handler_backslash_02.cc
index f5e8b216e7..ffc273a636 100644
--- a/tests/bits/parameter_handler_backslash_02.cc
+++ b/tests/bits/parameter_handler_backslash_02.cc
@@ -19,6 +19,18 @@
 #include <deal.II/base/parameter_handler.h>
 #include <fstream>
 
+/*
+ * Test that ParameterHandler can read parameters of the form
+ *
+ *     set Function = a,\
+ *                    \
+ *                    b,\
+ *     \
+ *                    c
+ *
+ * correctly. This tests how ParameterHandler handles lines that are blank
+ * aside from whitespace and a continuation ('\') character.
+ */
 
 int main ()
 {
diff --git a/tests/bits/parameter_handler_backslash_03.cc b/tests/bits/parameter_handler_backslash_03.cc
index 3b205e7be0..11ff875cf7 100644
--- a/tests/bits/parameter_handler_backslash_03.cc
+++ b/tests/bits/parameter_handler_backslash_03.cc
@@ -19,6 +19,14 @@
 #include <deal.II/base/parameter_handler.h>
 #include <fstream>
 
+/*
+ * Test that ParameterHandler does not join lines for things like
+ *
+ *     set Function = a,\ # first term
+ *                    b
+ *
+ * since there are non-whitespace characters after the '\'.
+ */
 
 int main ()
 {
diff --git a/tests/bits/parameter_handler_backslash_04.cc b/tests/bits/parameter_handler_backslash_04.cc
index 92fe3fe89a..376f8c40b2 100644
--- a/tests/bits/parameter_handler_backslash_04.cc
+++ b/tests/bits/parameter_handler_backslash_04.cc
@@ -19,6 +19,12 @@
 #include <deal.II/base/parameter_handler.h>
 #include <fstream>
 
+/*
+ * Test that ParameterHandler does *not* join lines for things like
+ *
+ *      set Function = a,\ b,
+ *                     c
+ */
 
 int main ()
 {
diff --git a/tests/bits/parameter_handler_backslash_05.cc b/tests/bits/parameter_handler_backslash_05.cc
index cd0b010ff7..0500ba9a07 100644
--- a/tests/bits/parameter_handler_backslash_05.cc
+++ b/tests/bits/parameter_handler_backslash_05.cc
@@ -19,6 +19,17 @@
 #include <deal.II/base/parameter_handler.h>
 #include <fstream>
 
+/*
+ * Test that ParameterHandler will stop a line continuation if a completely
+ * blank line follows one with a '\', such as
+ *
+ *     set Function_1 = a, \
+ *
+ *                      b, \
+ *                      c
+ *
+ * This should *not* be parsed as 'Function_1 = a, b, c'.
+ */
 
 int main ()
 {
diff --git a/tests/bits/parameter_handler_backslash_06.cc b/tests/bits/parameter_handler_backslash_06.cc
index 867870464e..a584306cf6 100644
--- a/tests/bits/parameter_handler_backslash_06.cc
+++ b/tests/bits/parameter_handler_backslash_06.cc
@@ -14,6 +14,11 @@
 // ---------------------------------------------------------------------
 
 
+/*
+ * Test that ParameterHandler will ignore whitespace characters following a
+ * '\' character when joining lines.
+ */
+
 #include "../tests.h"
 #include <deal.II/base/logstream.h>
 #include <deal.II/base/parameter_handler.h>
diff --git a/tests/bits/parameter_handler_backslash_07.cc b/tests/bits/parameter_handler_backslash_07.cc
index 765352f587..d9f16c6f2d 100644
--- a/tests/bits/parameter_handler_backslash_07.cc
+++ b/tests/bits/parameter_handler_backslash_07.cc
@@ -19,6 +19,18 @@
 #include <deal.II/base/parameter_handler.h>
 #include <fstream>
 
+/*
+ * If a parameter file line ends in a '\', then the whitespace at at the
+ * beginning of the next line is ignored when joining the lines. For example,
+ * the input
+ *
+ *      set value = val\
+ *                  u\
+ *                  e
+ *
+ * is parsed as 'set value = value'.
+ */
+
 
 int main ()
 {
-- 
2.39.5