Merge PR #265: Deprecate problematic config-options

Author: nene

README.md

@@ -149,13 +149,13 @@ All fields are optional and all fields that are not specified will be filled wit
 - [**`useTabs`**](docs/useTabs.md) to use tabs for indentation.
 - [**`keywordCase`**](docs/keywordCase.md) uppercases or lowercases keywords.
 - [**`indentStyle`**](docs/indentStyle.md) defines overall indentation style.
-- [**`multilineLists`**](docs/multilineLists.md) determines when to break lists of items to multiple lines.
+- [**`multilineLists`**](docs/multilineLists.md) **(DEPRECATED)** determines when to break lists of items to multiple lines.
 - [**`logicalOperatorNewline`**](docs/logicalOperatorNewline.md) newline before or after boolean operator (AND, OR, XOR).
 - [**`aliasAs`**](docs/aliasAs.md) enforces or forbids use of AS keyword for aliases.
 - [**`tabulateAlias`**](docs/tabulateAlias.md) aligns column aliases vertically.
 - [**`commaPosition`**](docs/commaPosition.md) where to place the comma in column lists.
-- [**`newlineBeforeOpenParen`**](docs/newlineBeforeOpenParen.md) placement of opening parenthesis.
-- [**`newlineBeforeCloseParen`**](docs/newlineBeforeCloseParen.md) placement of closing parenthesis.
+- [**`newlineBeforeOpenParen`**](docs/newlineBeforeOpenParen.md) **(DEPRECATED)** placement of opening parenthesis.
+- [**`newlineBeforeCloseParen`**](docs/newlineBeforeCloseParen.md) **(DEPRECATED)** placement of closing parenthesis.
 - [**`expressionWidth`**](docs/expressionWidth.md) maximum number of characters in parenthesized expressions to be kept on single line.
 - [**`linesBetweenQueries`**](docs/linesBetweenQueries.md) how many newlines to insert between queries.
 - [**`denseOperators`**](docs/denseOperators.md) packs operators densely without spaces.

docs/multilineLists.md

@@ -1,4 +1,4 @@
-# multilineLists
+# multilineLists (DEPRECATED)
 
 Determines when to break lists of items (e.g. columns in `SELECT` clause) to multiple lines.
 
@@ -116,3 +116,37 @@ SELECT first_name, last_name, occupation, age
 FROM persons
 GROUP BY age, occupation
 ```
+
+## Caveats
+
+This option has problematic behavior when dealing with comma-separated items within parenthesis.
+
+For example, with `multilineLists: "always"` you'd get this result:
+
+```
+INSERT INTO
+  records (25, 'John', 'Lennon', 1971, 'Imagine');
+
+INSERT INTO
+  records (
+    26,
+    'Michael',
+    'Jackson',
+    1997,
+    'Blood on the Dance Floor'
+  );
+```
+
+Which is not really always.
+
+And with `multilineLists: "avoid"` you'd get:
+
+```
+INSERT INTO records (25, 'John', 'Lennon', 1971, 'Imagine');
+
+INSERT INTO records (
+    26, 'Michael', 'Jackson', 1997, 'Blood on the Dance Floor'
+  );
+```
+
+Which still breaks things to multiple lines, but with incorrect indentation.

docs/newlineBeforeCloseParen.md

@@ -1,4 +1,4 @@
-# newlineBeforeCloseParen
+# newlineBeforeCloseParen (DEPRECATED)
 
 Decides whether to place close-parenthesis `)` of sub-queries on a separate line.
 
@@ -7,10 +7,6 @@ Decides whether to place close-parenthesis `)` of sub-queries on a separate line
 - `true` (default) adds newline before close-parenthesis.
 - `false` no newline.
 
-Caveats:
-
-This option is ignored when `indentStyle: "tabularLeft"` or `"tabularRight"` is used.
-
 ### newlineBeforeCloseParen: true
 
 ```
@@ -37,3 +33,8 @@ FROM
     FROM
       my_table );
 ```
+
+## Caveats
+
+- This option is ignored when `indentStyle: "tabularLeft"` or `"tabularRight"` is used.
+- This option is ignored when the parenthized content is smaller than `expressionWidth`.

docs/newlineBeforeOpenParen.md

@@ -1,4 +1,4 @@
-# newlineBeforeOpenParen
+# newlineBeforeOpenParen (DEPRECATED)
 
 Decides whether to place open-parenthesis `(` of sub-queries on a separate line.
 
@@ -7,10 +7,6 @@ Decides whether to place open-parenthesis `(` of sub-queries on a separate line.
 - `true` (default) adds newline before open-parenthesis.
 - `false` no newline.
 
-Caveats:
-
-This option is ignored when `indentStyle: "tabularLeft"` or `"tabularRight"` is used.
-
 ### newlineBeforeOpenParen: true
 
 ```
@@ -37,3 +33,9 @@ FROM (
       my_table
   );
 ```
+
+## Caveats
+
+- This option is ignored when `indentStyle: "tabularLeft"` or `"tabularRight"` is used.
+- This option is ignored when the parenthized content is smaller than `expressionWidth`.
+- This option is ignored for function calls.