Updated documentation in comments at the top of files.

I tried to standardize and expand the documentation and links to codex.wordpress.org in the comments at the top of most files.
Automattic · Jul 12, 2015 · de9c988 · de9c988
1 parent 5bb0534
commit de9c988
Show file tree

Hide file tree

Showing 24 changed files with 65 additions and 23 deletions.
diff --git a/404.php b/404.php
@@ -2,6 +2,8 @@
 /**
  * The template for displaying 404 pages (not found).
  *
+ * @link https://codex.wordpress.org/Creating_an_Error_404_Page
+ *
  * @package _s
  */
 

diff --git a/archive.php b/archive.php
@@ -2,7 +2,7 @@
 /**
  * The template for displaying archive pages.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link https://codex.wordpress.org/Template_Hierarchy
  *
  * @package _s
  */

diff --git a/comments.php b/comments.php
@@ -2,9 +2,11 @@
 /**
  * The template for displaying comments.
  *
- * The area of the page that contains both current comments
+ * This is the template that displays the area of the page that contains both the current comments
  * and the comment form.
  *
+ * @link https://codex.wordpress.org/Template_Hierarchy
+ *
  * @package _s
  */
 

diff --git a/footer.php b/footer.php
@@ -2,7 +2,9 @@
 /**
  * The template for displaying the footer.
  *
- * Contains the closing of the #content div and all content after
+ * Contains the closing of the #content div and all content after.
+ *
+ * @link https://developer.wordpress.org/themes/basics/template-files/#template-partials
  *
  * @package _s
  */

diff --git a/functions.php b/functions.php
@@ -1,6 +1,8 @@
 <?php
 /**
- * _s functions and definitions
+ * _s functions and definitions.
+ *
+ * @link https://codex.wordpress.org/Functions_File_Explained
  *
  * @package _s
  */

diff --git a/header.php b/header.php
@@ -2,7 +2,9 @@
 /**
  * The header for our theme.
  *
- * Displays all of the <head> section and everything up till <div id="content">
+ * This is the template that displays all of the <head> section and everything up until <div id="content">
+ *
+ * @link https://developer.wordpress.org/themes/basics/template-files/#template-partials
  *
  * @package _s
  */

diff --git a/inc/custom-header.php b/inc/custom-header.php
@@ -1,7 +1,6 @@
 <?php
 /**
- * Sample implementation of the Custom Header feature
- * http://codex.wordpress.org/Custom_Headers
+ * Sample implementation of the Custom Header feature.
  *
  * You can add an optional custom header image to header.php like so ...
  *
@@ -11,6 +10,8 @@
 	</a>
 	<?php endif; // End header image check. ?>
  *
+ * @link http://codex.wordpress.org/Custom_Headers
+ *
  * @package _s
  */
 

diff --git a/inc/customizer.php b/inc/customizer.php
@@ -1,6 +1,6 @@
 <?php
 /**
- * _s Theme Customizer
+ * _s Theme Customizer.
  *
  * @package _s
  */

diff --git a/inc/extras.php b/inc/extras.php
@@ -1,8 +1,8 @@
 <?php
 /**
- * Custom functions that act independently of the theme templates
+ * Custom functions that act independently of the theme templates.
  *
- * Eventually, some of the functionality here could be replaced by core features
+ * Eventually, some of the functionality here could be replaced by core features.
  *
  * @package _s
  */

diff --git a/inc/jetpack.php b/inc/jetpack.php
@@ -1,7 +1,8 @@
 <?php
 /**
- * Jetpack Compatibility File
- * See: https://jetpack.me/
+ * Jetpack Compatibility File.
+ *
+ * @link https://jetpack.me/
  *
  * @package _s
  */

diff --git a/index.php b/index.php
@@ -6,7 +6,8 @@
  * and one of the two required files for a theme (the other being style.css).
  * It is used to display a page when nothing more specific matches a query.
  * E.g., it puts together the home page when no home.php file exists.
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ *
+ * @link https://codex.wordpress.org/Template_Hierarchy
  *
  * @package _s
  */

diff --git a/js/customizer.js b/js/customizer.js
@@ -1,4 +1,6 @@
 /**
+ * customizer.js
+ *
  * Theme Customizer enhancements for a better user experience.
  *
  * Contains handlers to make Theme Customizer preview reload changes asynchronously.

diff --git a/js/skip-link-focus-fix.js b/js/skip-link-focus-fix.js
@@ -1,3 +1,10 @@
+/**
+ * skip-link-focus-fix.js
+ *
+ * Helps with accesability for keyboard only users.
+ *
+ * Learn more: https://github.com/Automattic/_s/pull/136
+ */
 ( function() {
 	var is_webkit = navigator.userAgent.toLowerCase().indexOf( 'webkit' ) > -1,
 	    is_opera  = navigator.userAgent.toLowerCase().indexOf( 'opera' )  > -1,

diff --git a/layouts/content-sidebar.css b/layouts/content-sidebar.css
@@ -1,6 +1,9 @@
 /*
-Theme Name: _s
-Layout: Content-Sidebar
+ * Theme Name: _s
+ *
+ * Layout: Content-Sidebar
+ *
+ * Learn more: https://developer.wordpress.org/themes/basics/template-files/
 */
 
 .content-area {

diff --git a/layouts/sidebar-content.css b/layouts/sidebar-content.css
@@ -1,6 +1,9 @@
 /*
-Theme Name: _s
-Layout: Sidebar-Content
+ * Theme Name: _s
+ *
+ * Layout: Sidebar-Content
+ *
+ * Learn more: https://developer.wordpress.org/themes/basics/template-files/
 */
 
 .content-area {

diff --git a/page.php b/page.php
@@ -4,9 +4,11 @@
  *
  * This is the template that displays all pages by default.
  * Please note that this is the WordPress construct of pages
- * and that other 'pages' on your WordPress site will use a
+ * and that other 'pages' on your WordPress site may use a
  * different template.
  *
+ * @link https://codex.wordpress.org/Template_Hierarchy
+ *
  * @package _s
  */
 

diff --git a/search.php b/search.php
@@ -2,6 +2,8 @@
 /**
  * The template for displaying search results pages.
  *
+ * @link https://developer.wordpress.org/themes/basics/template-hierarchy/#search-result
+ *
  * @package _s
  */
 

diff --git a/sidebar.php b/sidebar.php
@@ -2,6 +2,8 @@
 /**
  * The sidebar containing the main widget area.
  *
+ * @link https://developer.wordpress.org/themes/basics/template-files/#template-partials
+ *
  * @package _s
  */
 

diff --git a/single.php b/single.php
@@ -2,6 +2,8 @@
 /**
  * The template for displaying all single posts.
  *
+ * @link https://developer.wordpress.org/themes/basics/template-hierarchy/#single-post
+ *
  * @package _s
  */
 

diff --git a/template-parts/content-none.php b/template-parts/content-none.php
@@ -1,8 +1,8 @@
 <?php
 /**
- * The template part for displaying a message that posts cannot be found.
+ * Template part for displaying a message that posts cannot be found.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link https://codex.wordpress.org/Template_Hierarchy
  *
  * @package _s
  */

diff --git a/template-parts/content-page.php b/template-parts/content-page.php
@@ -1,6 +1,8 @@
 <?php
 /**
- * The template used for displaying page content in page.php
+ * Template part for displaying page content in page.php.
+ *
+ * @link https://codex.wordpress.org/Template_Hierarchy
  *
  * @package _s
  */

diff --git a/template-parts/content-search.php b/template-parts/content-search.php
@@ -1,8 +1,8 @@
 <?php
 /**
- * The template part for displaying results in search pages.
+ * Template part for displaying results in search pages.
  *
- * Learn more: http://codex.wordpress.org/Template_Hierarchy
+ * @link https://codex.wordpress.org/Template_Hierarchy
  *
  * @package _s
  */

diff --git a/template-parts/content-single.php b/template-parts/content-single.php
@@ -2,6 +2,8 @@
 /**
  * Template part for displaying single posts.
  *
+ * @link https://codex.wordpress.org/Template_Hierarchy
+ *
  * @package _s
  */
 

diff --git a/template-parts/content.php b/template-parts/content.php
@@ -2,6 +2,8 @@
 /**
  * Template part for displaying posts.
  *
+ * @link https://codex.wordpress.org/Template_Hierarchy
+ *
  * @package _s
  */
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,6 +2,8 @@ @@
     /**
      * The template for displaying 404 pages (not found).
      *
+     * @link https://codex.wordpress.org/Creating_an_Error_404_Page
+     *
      * @package _s
      */
@@ Expand Down @@