Admin Control Panel v2.0

✎ Editing: BlockCommentStandard.xml ← Back

<documentation title="Block Comment">
 <standard>
 <![CDATA[
 A block comment is a multi-line comment delimited by an opener "/*" and a closer "*/" which are each on their own line with the comment text in between.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: Uses a valid opener and closer.">
 <![CDATA[
/*
 A block comment.
*/
 ]]>
 </code>
 <code title="Invalid: Uses /** **/.">
 <![CDATA[
/**
 A block comment.
**/
 ]]>
 </code>
 </code_comparison>
 <code_comparison>
 <code title="Valid: Uses a valid opener and closer.">
 <![CDATA[
/*
 * A block comment
 * with multiple lines.
 */
 ]]>
 </code>
 <code title="Invalid: Uses multiple // or #.">
 <![CDATA[
// A block comment
// with multiple lines.

# A block comment
# with multiple lines.
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 Single line block comments are not allowed.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: Multi-line block comment.">
 <![CDATA[
/*
 A block comment.
*/
 ]]>
 </code>
 <code title="Invalid: Single line block comment.">
 <![CDATA[
/* A block comment. */
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 A block comment should not be empty.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: A block comment with contents.">
 <![CDATA[
/*
 A block comment.
*/
 ]]>
 </code>
 <code title="Invalid: An empty block comment.">
 <![CDATA[
/*

*/
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 Block comment text should start on a new line immediately after the opener.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: Text starts on a new line.">
 <![CDATA[
/*
 A block comment.
*/
 ]]>
 </code>
 <code title="Invalid: Text starts on the same line.">
 <![CDATA[
/* A block comment.
*/
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 If there are no asterisks at the start of each line, the contents of the docblock should be indented by at least 4 spaces.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: Indented by at least 4 spaces.">
 <![CDATA[
/*
 A block comment
 with multiple lines.
 And a second paragraph.
*/
 ]]>
 </code>
 <code title="Invalid: Indented by less than 4 spaces.">
 <![CDATA[
/*
 A block comment
 with
 multiple lines.
*/
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 If asterisks are used, they should be aligned.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: Asterisks are aligned.">
 <![CDATA[
/*
 * A block comment
 * with
 * multiple lines.
 */
 ]]>
 </code>
 <code title="Invalid: Asterisks are not aligned.">
 <![CDATA[
/*
 * A block comment
 * with
 * multiple lines.
*/
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 A block comment should start with a capital letter.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: Starts with a capital letter.">
 <![CDATA[
/*
 A block comment.
*/
 ]]>
 </code>
 <code title="Invalid: Does not start with a capital letter.">
 <![CDATA[
/*
 a block comment.
*/
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 The block comment closer should be on a new line.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: Closer is on a new line.">
 <![CDATA[
/*
 A block comment.
*/
 ]]>
 </code>
 <code title="Invalid: Closer is not on a new line.">
 <![CDATA[
/*
 A block comment. */
 ]]>
 </code>
 </code_comparison>
 <standard>
 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.
 </standard>
 <code_comparison>
 <code title="Valid: The closer's asterisk is aligned with other asterisks.">
 <![CDATA[
/*
 * A block comment
 */
 ]]>
 </code>
 <code title="Invalid: The closer's asterisk is not aligned with other asterisks.">
 <![CDATA[
/*
 * A block comment.
*/
 ]]>
 </code>
 </code_comparison>
 <code_comparison>
 <code title="Valid: The closer's asterisk is aligned with the opener's slash.">
 <![CDATA[
/*
 A block comment.
*/
 ]]>
 </code>
 <code title="Invalid: The closer's asterisk is not aligned with the opener's slash.">
 <![CDATA[
/*
 A block comment.
 */
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 There should be an empty line after the block comment.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: An empty line after the comment.">
 <![CDATA[
/*
 A block comment.
*/

echo 'Content';
 ]]>
 </code>
 <code title="Invalid: No empty line after the comment.">
 <![CDATA[
/*
 A block comment.
*/
echo 'Content';
 ]]>
 </code>
 </code_comparison>
 <standard>
 <![CDATA[
 A block comment immediately after a PHP open tag should not have a preceeding blank line.
 ]]>
 </standard>
 <code_comparison>
 <code title="Valid: No blank line after an open tag.">
 <![CDATA[
<?php
/*
 * A block comment
 * with
 * multiple lines.
 */
 ]]>
 </code>
 <code title="Invalid: A blank line after an open tag.">
 <![CDATA[
<?php

/*
 * A block comment
 * with
 * multiple lines.
 */
 ]]>
 </code>
 </code_comparison>
</documentation>

Cancel