Merge pull request #347 from olefredrik/fix/fileDocComments

Added better file doc comments

.travis.yml

@@ -1,47 +1,50 @@
-# Travis CI (MIT License) configuration file for the FoundationPress WordPress theme
+# Travis CI (MIT License) configuration file for the FoundationPress WordPress theme.
 # @link https://travis-ci.org/
 
-# For use with the FoundationPress WordPress theme
-# @link https://github.com/olefredrik/FoundationPress
+# For use with the FoundationPress WordPress theme.
+# @link https://github.com/olefredrik/foundationpress
 
 # Declare project language.
 # @link http://about.travis-ci.org/docs/user/languages/php/
 language: php
 
 # Declare versions of PHP to use. Use one decimal max.
 php:
-    # aliased to a recent 5.5.x version
-    - "5.5"
-    # aliased to a recent 5.4.x version
-    - "5.4"
-    # aliased to a recent 5.3.x version
-    - "5.3"
-    # Current $required_php_version for WordPress: 5.2.4
-    - "5.2"
+  # aliased to a recent 5.5.x version
+  - "5.5"
+  # aliased to a recent 5.4.x version
+  - "5.4"
+  # aliased to a recent 5.3.x version
+  - "5.3"
+  # Current $required_php_version for WordPress: 5.2.4
+  - "5.2"
 
 # Declare which versions of WordPress to test against.
 # Also declare whether or not to test in Multisite.
 env:
-    # Trunk
-    # @link https://github.com/WordPress/WordPress
-    - WP_VERSION=master WP_MULTISITE=0
-    # WordPress 4.1
-    # @link https://github.com/WordPress/WordPress/tree/4.1-branch
-    - WP_VERSION=4.1 WP_MULTISITE=0
-    # WordPress 4.0
-    # @link https://github.com/WordPress/WordPress/tree/4.0-branch
-    - WP_VERSION=4.0 WP_MULTISITE=0
+  # Trunk
+  # @link https://github.com/WordPress/WordPress
+  - WP_VERSION=master WP_MULTISITE=0
+  - WP_VERSION=master WP_MULTISITE=1
+  # WordPress 4.2
+  # @link https://github.com/WordPress/WordPress/tree/4.2-branch
+  - WP_VERSION=4.2 WP_MULTISITE=0
+  - WP_VERSION=4.2 WP_MULTISITE=1
+  # WordPress 4.1
+  # @link https://github.com/WordPress/WordPress/tree/4.1-branch
+  - WP_VERSION=4.1 WP_MULTISITE=0
+  - WP_VERSION=4.1 WP_MULTISITE=1
 
 # Declare 5.6 beta in test matrix.
 # @link https://buddypress.trac.wordpress.org/ticket/5620
 # @link http://docs.travis-ci.com/user/build-configuration/
 matrix:
-    include:
-        - php: 5.6
-          env: WP_VERSION=master
-    allow_failures:
-        - php: 5.6
-    fast_finish: true
+  include:
+    - php: 5.6
+      env: WP_VERSION=master
+  allow_failures:
+    - php: 5.6
+  fast_finish: true
 
 # Use this to prepare the system to install prerequisites or dependencies.
 # e.g. sudo apt-get update.
@@ -52,59 +55,57 @@ matrix:
 # e.g. copy database configurations, environment variables, etc.
 # Failures in this section will result in build status 'errored'.
 before_script:
-    # Set up WordPress installation.
-    - export WP_DEVELOP_DIR=/tmp/wordpress/
-    - mkdir -p $WP_DEVELOP_DIR
-    # Use the Git mirror of WordPress.
-    - git clone --depth=1 --branch="$WP_VERSION" git://develop.git.wordpress.org/ $WP_DEVELOP_DIR
-    # Set up theme information.
-    - theme_slug=$(basename $(pwd))
-    - theme_dir=$WP_DEVELOP_DIR/src/wp-content/themes/$theme_slug
-    - cd ..
-    - mv $theme_slug $theme_dir
-    # Set up WordPress configuration.
-    - cd $WP_DEVELOP_DIR
-    - echo $WP_DEVELOP_DIR
-    - cp wp-tests-config-sample.php wp-tests-config.php
-    - sed -i "s/youremptytestdbnamehere/wordpress_test/" wp-tests-config.php
-    - sed -i "s/yourusernamehere/root/" wp-tests-config.php
-    - sed -i "s/yourpasswordhere//" wp-tests-config.php
-    # Create WordPress database.
-    - mysql -e 'CREATE DATABASE wordpress_test;' -uroot
-    # Install CodeSniffer for WordPress Coding Standards checks.
-    - git clone https://github.com/squizlabs/PHP_CodeSniffer.git php-codesniffer
-    # Install WordPress Coding Standards.
-    - git clone https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git wordpress-coding-standards
-    # Hop into CodeSniffer directory.
-    - cd php-codesniffer
-    # Set install path for WordPress Coding Standards
-    # @link https://github.com/squizlabs/PHP_CodeSniffer/blob/4237c2fc98cc838730b76ee9cee316f99286a2a7/CodeSniffer.php#L1941
-    - scripts/phpcs --config-set installed_paths ../wordpress-coding-standards
-    # Hop into themes directory.
-    - cd $theme_dir
-    # After CodeSniffer install you should refresh your path.
-    - phpenv rehash
+  # Set up WordPress installation.
+  - export WP_DEVELOP_DIR=/tmp/wordpress/
+  - mkdir -p $WP_DEVELOP_DIR
+  # Use the Git mirror of WordPress.
+  - git clone --depth=1 --branch="$WP_VERSION" git://develop.git.wordpress.org/ $WP_DEVELOP_DIR
+  # Set up theme information.
+  - theme_slug=$(basename $(pwd))
+  - theme_dir=$WP_DEVELOP_DIR/src/wp-content/themes/$theme_slug
+  - cd ..
+  - mv $theme_slug $theme_dir
+  # Set up WordPress configuration.
+  - cd $WP_DEVELOP_DIR
+  - echo $WP_DEVELOP_DIR
+  - cp wp-tests-config-sample.php wp-tests-config.php
+  - sed -i "s/youremptytestdbnamehere/wordpress_test/" wp-tests-config.php
+  - sed -i "s/yourusernamehere/root/" wp-tests-config.php
+  - sed -i "s/yourpasswordhere//" wp-tests-config.php
+  # Create WordPress database.
+  - mysql -e 'CREATE DATABASE wordpress_test;' -uroot
+  # Install CodeSniffer for WordPress Coding Standards checks.
+  - git clone https://github.com/squizlabs/PHP_CodeSniffer.git php-codesniffer
+  # Install WordPress Coding Standards.
+  - git clone https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git wordpress-coding-standards
+  # Hop into CodeSniffer directory.
+  - cd php-codesniffer
+  # Set install path for WordPress Coding Standards.
+  # @link https://github.com/squizlabs/PHP_CodeSniffer/blob/4237c2fc98cc838730b76ee9cee316f99286a2a7/CodeSniffer.php#L1941
+  - scripts/phpcs --config-set installed_paths ../wordpress-coding-standards
+  # Hop into themes directory.
+  - cd $theme_dir
+  # After CodeSniffer install you should refresh your path.
+  - phpenv rehash
 
 # Run test script commands.
 # Default is specific to project language.
 # All commands must exit with code 0 on success. Anything else is considered failure.
 script:
-    # Search for PHP syntax errors.
-    - find . \( -name '*.php' \) -exec php -lf {} \;
-    # WordPress Coding Standards
-    # @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
-    # @link http://pear.php.net/package/PHP_CodeSniffer/
-    # -p flag: Show progress of the run.
-    # -s flag: Show sniff codes in all reports.
-    # -v flag: Print verbose output.
-    # -n flag: Do not print warnings (shortcut for --warning-severity=0)
-    # --standard: Use WordPress as the standard.
-    # --extensions: Only sniff PHP files.
-    # --ignore: Ignore these files/directories
-    - $WP_DEVELOP_DIR/php-codesniffer/scripts/phpcs -p -s -v -n . --standard=./codesniffer.ruleset.xml --extensions=php --ignore=./bower_components/
-
+  # Search for PHP syntax errors.
+  - find . \( -name '*.php' \) -exec php -lf {} \;
+  # WordPress Coding Standards
+  # @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
+  # @link http://pear.php.net/package/PHP_CodeSniffer/
+  # -p flag: Show progress of the run.
+  # -s flag: Show sniff codes in all reports.
+  # -v flag: Print verbose output.
+  # -n flag: Do not print warnings. (shortcut for --warning-severity=0)
+  # --standard: Use WordPress as the standard.
+  # --extensions: Only sniff PHP files.
+  - $WP_DEVELOP_DIR/php-codesniffer/scripts/phpcs -p -s -v -n . --standard=./codesniffer.ruleset.xml --extensions=php
 
 # Receive notifications for build results.
 # @link http://docs.travis-ci.com/user/notifications/#Email-notifications
 notifications:
-    email: false
+  email: false

404.php

@@ -1,4 +1,13 @@
-<?php get_header(); ?>
+<?php
+/**
+ * The template for displaying 404 pages (not found)
+ *
+ * @package WordPress
+ * @subpackage FoundationPress
+ * @since FoundationPress 1.0
+ */
+
+get_header(); ?>
 
 <div class="row">
 	<div class="small-12 large-8 columns" role="main">

archive.php

@@ -1,4 +1,23 @@
-<?php get_header(); ?>
+<?php
+/**
+ * The template for displaying archive pages
+ *
+ * Used to display archive-type pages if nothing more specific matches a query.
+ * For example, puts together date-based pages if no date.php file exists.
+ *
+ * If you'd like to further customize these archive views, you may create a
+ * new template file for each one. For example, tag.php (Tag archives),
+ * category.php (Category archives), author.php (Author archives), etc.
+ *
+ * @link https://codex.wordpress.org/Template_Hierarchy
+ *
+ * @package WordPress
+ * @subpackage FoundationPress
+ * @since FoundationPress 1.0
+ */
+
+get_header(); ?>
+
 <div class="row">
 <!-- Row for main content area -->
 	<div class="small-12 large-8 columns" role="main">
@@ -13,7 +32,7 @@
 		<?php else : ?>
 			<?php get_template_part( 'content', 'none' ); ?>
 
-	<?php endif; // end have_posts() check ?>
+	<?php endif; // End have_posts() check. ?>
 
 	<?php /* Display navigation to next/previous pages when applicable */ ?>
 	<?php if ( function_exists( 'foundationpress_pagination' ) ) { foundationpress_pagination(); } else if ( is_paged() ) { ?>

codesniffer.ruleset.xml

@@ -1,19 +1,34 @@
 <?xml version="1.0"?>
-<ruleset name="FoundationPress Theme, WordPress Coding Standards Configuration">
+<ruleset name="WordPress Theme Coding Standards">
 	<!-- See https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml -->
 	<!-- See https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/blob/develop/WordPress-Core/ruleset.xml -->
 
 	<!-- Set a description for this ruleset. -->
-	<description>A series of tests used to check FoundationPress for compliance with WordPress Coding Standards</description>
+	<description>A custom set of code standard rules to check for WordPress themes.</description>
 
 	<!-- Include the WordPress ruleset, with exclusions. -->
 	<rule ref="WordPress">
+		<exclude name="Generic.WhiteSpace.ScopeIndent.IncorrectExact" />
 		<exclude name="Generic.WhiteSpace.ScopeIndent.Incorrect" />
+		<exclude name="Generic.Files.EndFileNewline.NotFound" />
+		<exclude name="Generic.Formatting.DisallowMultipleStatements.SameLine" />
+		<exclude name="Generic.Functions.OpeningFunctionBraceKernighanRitchie.ContentAfterBrace" />
 		<exclude name="PEAR.Functions.FunctionCallSignature.Indent" />
-		<exclude name="Generic.WhiteSpace.ScopeIndent.IncorrectExact" />
+		<exclude name="PEAR.Functions.FunctionCallSignature.SpaceAfterOpenBracket" />
+		<exclude name="PEAR.Functions.FunctionCallSignature.SpaceBeforeCloseBracket" />
+
+		<exclude name="Squiz.Commenting.FileComment.WrongStyle" />
+		<exclude name="Squiz.Commenting.BlockComment.NoEmptyLineBefore" />
+		<exclude name="Squiz.Commenting.FunctionComment.MissingParamTag" />
+		<exclude name="Squiz.Commenting.VariableComment.WrongStyle" />
+		<exclude name="Squiz.Commenting.FunctionComment.Missing" />
+		<exclude name="Squiz.Commenting.FunctionComment.WrongStyle" />
+		<exclude name="Squiz.Commenting.InlineComment.InvalidEndChar" />
+		<exclude name="Squiz.Commenting.ClassComment.Missing" />
 
-		<exclude name="WordPress.XSS.EscapeOutput" />
-		<exclude name="WordPress.WhiteSpace.ScopeIndent.Incorrect" />
+		<exclude name="WordPress.XSS.EscapeOutput.UnsafePrintingFunction" />
+		<exclude name="WordPress.XSS.EscapeOutput.OutputNotEscaped" />
+		<exclude name="WordPress.Arrays.ArrayDeclaration.NoSpaceAfterOpenParenthesis" />
 		<exclude name="WordPress.Variables.GlobalVariables" />
 	</rule>
 </ruleset>

comments.php

@@ -1,4 +1,15 @@
 <?php
+/**
+ * The template for displaying comments
+ *
+ * The area of the page that contains both current comments
+ * and the comment form.
+ *
+ * @package WordPress
+ * @subpackage FoundationPress
+ * @since FoundationPress 1.0
+ */
+
 if ( have_comments() ) :
 	if ( (is_page() || is_single()) && ( ! is_home() && ! is_front_page()) ) :
 ?>
@@ -35,9 +46,12 @@
 ?>
 
 <?php
-	// Do not delete these lines
 
-	// Prevent access to this file directly
+	/*
+	Do not delete these lines.
+	Prevent access to this file directly
+	*/
+
 	defined( 'ABSPATH' ) or die( __( 'Please do not load this page directly. Thanks!', 'foundationpress' ) );
 
 	if ( post_password_required() ) { ?>
@@ -66,30 +80,53 @@
 		<p><?php printf( __( 'Logged in as <a href="%s/wp-admin/profile.php">%s</a>.', 'foundationpress' ), get_option( 'siteurl' ), $user_identity ); ?> <a href="<?php echo wp_logout_url( get_permalink() ); ?>" title="<?php __( 'Log out of this account', 'foundationpress' ); ?>"><?php _e( 'Log out &raquo;', 'foundationpress' ); ?></a></p>
 		<?php else : ?>
 		<p>
-			<label for="author"><?php _e( 'Name', 'foundationpress' ); if ( $req ) { _e( ' (required)', 'foundationpress' ); } ?></label>
+			<label for="author">
+				<?php
+					_e( 'Name', 'foundationpress' ); if ( $req ) { _e( ' (required)', 'foundationpress' ); }
+				?>
+			</label>
 			<input type="text" class="five" name="author" id="author" value="<?php echo esc_attr( $comment_author ); ?>" size="22" tabindex="1" <?php if ( $req ) { echo "aria-required='true'"; } ?>>
 		</p>
 		<p>
-			<label for="email"><?php _e( 'Email (will not be published)', 'foundationpress' ); if ( $req ) { _e( ' (required)', 'foundationpress' ); } ?></label>
+			<label for="email">
+				<?php
+					_e( 'Email (will not be published)', 'foundationpress' ); if ( $req ) { _e( ' (required)', 'foundationpress' ); }
+				?>
+			</label>
 			<input type="text" class="five" name="email" id="email" value="<?php echo esc_attr( $comment_author_email ); ?>" size="22" tabindex="2" <?php if ( $req ) { echo "aria-required='true'"; } ?>>
 		</p>
 		<p>
-			<label for="url"><?php _e( 'Website', 'foundationpress' ); ?></label>
+			<label for="url">
+				<?php
+					_e( 'Website', 'foundationpress' );
+				?>
+			</label>
 			<input type="text" class="five" name="url" id="url" value="<?php echo esc_attr( $comment_author_url ); ?>" size="22" tabindex="3">
 		</p>
 		<?php endif; ?>
 		<p>
-			<label for="comment"><?php _e( 'Comment', 'foundationpress' ); ?></label>
+			<label for="comment">
+					<?php
+						_e( 'Comment', 'foundationpress' );
+					?>
+			</label>
 			<textarea name="comment" id="comment" tabindex="4"></textarea>
 		</p>
-		<p id="allowed_tags" class="small"><strong>XHTML:</strong> <?php _e( 'You can use these tags:','foundationpress' ); ?> <code><?php echo allowed_tags(); ?></code></p>
+		<p id="allowed_tags" class="small"><strong>XHTML:</strong> 
+			<?php
+				_e( 'You can use these tags:','foundationpress' );
+			?> 
+			<code>
+				<?php echo allowed_tags(); ?>
+			</code>
+		</p>
 		<p><input name="submit" class="button" type="submit" id="submit" tabindex="5" value="<?php esc_attr_e( 'Submit Comment', 'foundationpress' ); ?>"></p>
 		<?php comment_id_fields(); ?>
 		<?php do_action( 'comment_form', $post->ID ); ?>
 	</form>
-	<?php endif; // If registration required and not logged in ?>
+	<?php endif; // If registration required and not logged in. ?>
 </section>
 <?php
-	endif; // if you delete this the sky will fall on your head
-endif; // if you delete this the sky will fall on your head
-?>
+	endif; // If you delete this the sky will fall on your head.
+	endif; // If you delete this the sky will fall on your head.
+?>

content-none.php

@@ -1,10 +1,14 @@
 <?php
 /**
- * The template for displaying a "No posts found" message
+ * The template part for displaying a message that posts cannot be found
  *
+ * Learn more: {@link https://codex.wordpress.org/Template_Hierarchy}
+ *
+ * @package WordPress
  * @subpackage FoundationPress
  * @since FoundationPress 1.0
  */
+
 ?>
 
 <header class="page-header">