From 576382ce660378cb26b6f780058b66f3b04ec3c0 Mon Sep 17 00:00:00 2001 From: costdev Date: Thu, 27 Feb 2025 09:43:49 +0000 Subject: [PATCH 01/16] Add documentation for Squiz.Commenting.BlockComment. --- .../Docs/Commenting/BlockCommentStandard.xml | 316 ++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml new file mode 100644 index 0000000000..8401ef14e1 --- /dev/null +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -0,0 +1,316 @@ + + + + + + + + + + /** + A block comment. +*/ + ]]> + + + + + + + + **/ + ]]> + + + + + + + + /** + A block comment. +**/ + ]]> + + + + + + + + // A block comment +// with +// multiple lines. + ]]> + + + + + + + + # A block comment +# with +# multiple lines. + ]]> + + + + + + + + + + + A block comment + with + multiple lines. +*/ + ]]> + + + + + + + + + + + * with + * multiple lines. +*/ + ]]> + + + + + + + + + + + +*/ + ]]> + + + + + + + + + + + /* A block comment. */ + ]]> + + + + + + + + + + + A block comment. +*/ + ]]> + + + + + + + + + + + A block comment. */ + ]]> + + + + + + + + + + + + A block comment. +*/ + ]]> + + + + + + + + + + + echo 'Content'; + ]]> + + + + + + + + + + + a block comment. +*/ + ]]> + + + + + + + + + + + +/* + * A block comment + * with + * multiple lines. + */ + ]]> + + + \ No newline at end of file From c0747c7596cf50ddc618d916fe7cbbfc07c91b88 Mon Sep 17 00:00:00 2001 From: Colin Stewart <79332690+costdev@users.noreply.github.com> Date: Sat, 8 Mar 2025 08:20:30 +0000 Subject: [PATCH 02/16] Apply suggestions from code review Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com> --- .../Squiz/Docs/Commenting/BlockCommentStandard.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 8401ef14e1..3882819f80 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -90,7 +90,7 @@ @@ -98,8 +98,8 @@ @@ -165,14 +165,14 @@ ]]> - + - + /* A block comment. */ ]]> From e122f81fa166e133a1a35137e7cb1c8109b3acd7 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 10:43:25 +0000 Subject: [PATCH 03/16] Add a short description of a block comment. --- src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 3882819f80..83791bb0e8 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -1,7 +1,7 @@ From 5d1a3dc119ebc8a8e56c2c5b179361d1d7f5eb88 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 10:45:29 +0000 Subject: [PATCH 04/16] Improve opener/closer descriptions and comparisons. --- .../Docs/Commenting/BlockCommentStandard.xml | 65 +++---------------- 1 file changed, 8 insertions(+), 57 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 83791bb0e8..498482c71c 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -5,39 +5,7 @@ ]]> - - - - - /** - A block comment. -*/ - ]]> - - - - - - - - **/ - ]]> - - - - + - + - + // A block comment -// with -// multiple lines. - ]]> - - - - - - - - // with multiple lines. + # A block comment -# with -# multiple lines. +# with multiple lines. ]]> From cb43ef79a9da32d6baeb9c5e595b359ef16a790e Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:10:46 +0000 Subject: [PATCH 05/16] Merge `HasEmptyLine` and `NoNewLine` entries. --- .../Docs/Commenting/BlockCommentStandard.xml | 24 +------------------ 1 file changed, 1 insertion(+), 23 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 498482c71c..da7b3bd530 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -131,7 +131,7 @@ @@ -171,28 +171,6 @@ - - - - - - - - A block comment. -*/ - ]]> - - - - From 22d04152578afb25ba9425d2ed051d7f948aa941 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 10:55:45 +0000 Subject: [PATCH 06/16] Add guidance for `LastLineIndent`. --- .../Docs/Commenting/BlockCommentStandard.xml | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index da7b3bd530..9b52e689be 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -242,4 +242,39 @@ echo 'Content'; ]]> + + If asterisks are used, the closer's asterisk should be aligned with these. Otherwise, the closer's asterisk should be aligned with the opener's slash. + + + + */ + ]]> + + + */ + ]]> + + + + + */ + ]]> + + + */ + ]]> + + \ No newline at end of file From 53402a57f9ea44fb12e32245220055840f9e0fdb Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:12:11 +0000 Subject: [PATCH 07/16] Make `SingleLine` guidance second. --- .../Docs/Commenting/BlockCommentStandard.xml | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 9b52e689be..f2b004ff0a 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -41,6 +41,25 @@ + + + + + + + /* A block comment. */ + ]]> + + + + @@ -112,25 +131,6 @@ - - - - - - - /* A block comment. */ - ]]> - - - - From e66d021f82efdc4e1fdc1f1227687996e8305726 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:12:58 +0000 Subject: [PATCH 08/16] Make `Empty` guidance third. --- .../Docs/Commenting/BlockCommentStandard.xml | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index f2b004ff0a..3937b4fa32 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -60,6 +60,27 @@ + + + + + + + +*/ + ]]> + + + + @@ -110,27 +131,6 @@ - - - - - - - -*/ - ]]> - - - - From 3823a4a1c153802e1c09e3ed58748722b74bfd99 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:13:59 +0000 Subject: [PATCH 09/16] Make `HasEmptyLine`/`NoNewLine` guidance fourth. --- .../Docs/Commenting/BlockCommentStandard.xml | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 3937b4fa32..214eaaa35a 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -75,6 +75,26 @@ +*/ + ]]> + + + + + + + + + + + A block comment. */ ]]> @@ -131,26 +151,6 @@ - - - - - - - A block comment. -*/ - ]]> - - - - From 3e97c0902fe4dc3f26eda6e61df8c8e96c569501 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:15:17 +0000 Subject: [PATCH 10/16] Make `NoCapital` guidance seventh. --- .../Docs/Commenting/BlockCommentStandard.xml | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 214eaaa35a..e3895e30d5 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -151,66 +151,66 @@ - + - + A block comment. */ + a block comment. +*/ ]]> - + - + echo 'Content'; + A block comment. */ ]]> - + - + a block comment. + A block comment. */ +echo 'Content'; ]]> From 7b75bd1f9a17ad07b57e097eb2a0ca8dee3230aa Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:17:43 +0000 Subject: [PATCH 11/16] Make `LastLineIndent` guidance ninth. --- .../Docs/Commenting/BlockCommentStandard.xml | 70 +++++++++---------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index e3895e30d5..9372730f7d 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -191,6 +191,41 @@ + If asterisks are used, the closer's asterisk should be aligned with these. Otherwise, the closer's asterisk should be aligned with the opener's slash. + + + + */ + ]]> + + + */ + ]]> + + + + + */ + ]]> + + + */ + ]]> + + + @@ -242,39 +277,4 @@ echo 'Content'; ]]> - - If asterisks are used, the closer's asterisk should be aligned with these. Otherwise, the closer's asterisk should be aligned with the opener's slash. - - - - */ - ]]> - - - */ - ]]> - - - - - */ - ]]> - - - */ - ]]> - - \ No newline at end of file From fd0b00d75009a30684f0dab909907730a16dbbe7 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:18:37 +0000 Subject: [PATCH 12/16] Clarify that "open tag" means "PHP open tag". --- src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 9372730f7d..6a3195c6ef 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -251,7 +251,7 @@ echo 'Content'; From 2280060138bc3e267831ae0a53d490d7ecab0470 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 16 Mar 2025 11:27:29 +0000 Subject: [PATCH 13/16] Improve `` usage. --- .../Docs/Commenting/BlockCommentStandard.xml | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 6a3195c6ef..dac172ffe5 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -7,9 +7,9 @@ /* A block comment. -*/ +*/ ]]> @@ -23,10 +23,10 @@ /* * A block comment * with multiple lines. -*/ + */ ]]> @@ -47,9 +47,9 @@ /* A block comment. -*/ +*/ ]]> @@ -67,7 +67,7 @@ A block comment. */ ]]> @@ -88,7 +88,7 @@ A block comment. */ ]]> @@ -108,9 +108,9 @@ A block comment + with multiple lines. + And a second paragraph. */ ]]> @@ -132,20 +132,20 @@ * + * A block comment + * with + * multiple lines. + */ ]]> * with + * with * multiple lines. -*/ +*/ ]]> @@ -158,7 +158,7 @@ A block comment. */ ]]> @@ -180,13 +180,13 @@ */ ]]> A block comment. */ + A block comment. */ ]]> @@ -196,32 +196,32 @@ */ +/* + * A block comment + */ ]]> */ +*/ ]]> /* A block comment. -*/ +*/ ]]> */ + */ ]]> @@ -236,7 +236,7 @@ /* A block comment. */ - + echo 'Content'; ]]> @@ -258,7 +258,7 @@ echo 'Content'; /* * A block comment * with * multiple lines. From 3e6fe4510ccaae240193947f8fabf7cec6cc0d8e Mon Sep 17 00:00:00 2001 From: costdev Date: Thu, 20 Mar 2025 12:58:44 +0000 Subject: [PATCH 14/16] End the file on a new line. --- src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index dac172ffe5..9f81638d40 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -277,4 +277,4 @@ echo 'Content'; ]]> - \ No newline at end of file + From 4e45f1b537d792e49fd18aa116ddb1ce80a40d4f Mon Sep 17 00:00:00 2001 From: Colin Stewart <79332690+costdev@users.noreply.github.com> Date: Sun, 23 Mar 2025 22:07:07 +0000 Subject: [PATCH 15/16] Suggested text change to the first standard. Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com> --- src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 9f81638d40..282cf6bbd0 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -1,7 +1,7 @@ From 98dc9607ecf5fd78090f36e8ff75faff3b7b4a53 Mon Sep 17 00:00:00 2001 From: costdev Date: Sun, 23 Mar 2025 22:07:43 +0000 Subject: [PATCH 16/16] Use `multi-line` instead of `multiline`. --- src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml index 282cf6bbd0..0e6a6b85b7 100644 --- a/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml +++ b/src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml @@ -1,7 +1,7 @@