tidy up misc doc blocks, regenerate rst files

docs/api/inc/ajax-functions.rst

@@ -26,20 +26,24 @@ inc/ajax-functions.php
 
    :global: $_POST
 
-   :see: largo_load_more_posts_choose_partial
+   :uses: largo_load_more_posts_choose_partial
+
+   :uses: largo_get_partial_by_post_type
 
 .. php:function:: largo_load_more_posts_choose_partial()
 
    Function to determine which partial slug should be used by LMP to render posts.
 
    Includes a "largo_lmp_template_partial" filter to allow for modifying the value $partial.
 
-   :param object $post_query: The query object being used to generate LMP markup
+   :param WP_Query $post_query: The WP_Query being used to generate LMP markup
 
    :returns: string $partial The slug of partial that should be loaded.
 
    :global: $opt
 
    :global: $_POST
 
-   :see: largo_load_more_posts
+   :see: largo_load_more_posts
+
+   :since: 0.5.3

docs/api/inc/enqueue.rst

@@ -1,8 +1,42 @@
 inc/enqueue.php
 ===============
 
+.. php:function:: largo_enqueue_js()
+
+   Enqueue our core javascript and css files
+
+   :since: 1.0
+
+   :global: LARGO_DEBUG
+
+.. php:function:: largo_enqueue_child_theme_css()
+
+   Enqueue Largo child theme CSS
+
+   :since: 0.5.4
+
 .. php:function:: largo_enqueue_admin_scripts()
 
    Enqueue our admin javascript and css files
 
-   :global: LARGO_DEBUG
+   :global: LARGO_DEBUG
+
+.. php:function:: largo_header_js()
+
+   Determine which size of the banner image to load based on the window width
+
+   TODO: this should probably use picturefill for this instead
+
+   :since: 1.0
+
+.. php:function:: largo_footer_js()
+
+   Additional scripts to load in the footer (mostly for various social widgets)
+
+   :since: 1.0
+
+.. php:function:: largo_google_analytics()
+
+   Add Google Analytics code to the footer, you need to add your GA ID to the theme settings for this to work
+
+   :since: 1.0

docs/api/inc/post-templates.rst

@@ -21,7 +21,7 @@ inc/post-templates.php
    The changes to the content in this function should eventually be made
    perminant in the database. (@see https://github.com/INN/Largo/issues/354)
 
-   :since: v0.4
+   :since: 0.4
    :param String $content: the post content passed in by WordPress filter
 
    :returns: String $iltered post content.
@@ -31,8 +31,26 @@ inc/post-templates.php
    Retrieves the attachment ID from the file URL
    (or that of any thumbnail image)
 
-   :since: v0.4
+   :since: 0.4
 
    :see: https://pippinsplugins.com/retrieve-attachment-id-from-image-url/
 
-   :returns: Int $D of post attachment (or false if not found)
+   :returns: Int $D of post attachment (or false if not found)
+
+.. php:function:: largo_get_partial_by_post_type()
+
+   Given a post type and an optional context, return the partial that should be loaded for that sort of post.
+
+   The default context is search, and the context isn't actually used by this function,
+   but it is passed to the filter this function runs, largo_partial_by_post_type.
+
+   :link: https://github.com/INN/Largo/issues/1023
+   :param string $partial: Required, the default partial in this context.
+   :param string $post_type: Required, the given post's post type
+   :param string $context: Required, the context of this partial.
+
+   :returns: string $he partial that should be loaded. This defaults to 'search'.
+
+   :filter: largo_partial_by_post_type
+
+   :since: 0.5.4

docs/api/inc/term-meta.rst

@@ -5,10 +5,38 @@ inc/term-meta.php
 
    Get the proxy post for a term
 
-   :param string $taxnomy:
-   :param int $term_id:
+   :param string $taxnomy: The taxonomy of the term for which you want to retrieve a term meta post
+   :param int $term_id: The ID of the term
+
+   :returns: int $post_id The ID of the term meta post
+
+.. php:function:: largo_add_term_featured_media_button()
+
+   Add the "Set Featured Media" button in the term edit page
+
+   :since: 0.5.4
+
+   :see: largo_term_featured_media_enqueue_post_editor
+
+.. php:function:: largo_term_featured_media_enqueue_post_editor()
+
+   Enqueue wordpress post editor on term edit page
+
+   :param string $hook: the page this is being called upon.
+
+   :since: 0.5.4
+
+   :see: largo_term_featured_media_button
+
+.. php:function:: largo_term_featured_media_types()
+
+   Removes the embed-code, video and gallery media types from the term featured media editor
+
+   :param array $types: array of media types that can be used with the featured media editor
+
+   :since: 0.5.4
 
-   :returns: int $post_id
+   :global: $post $sed to determine whether or not this button is being called on a post or on something else.
 
 .. php:function:: largo_add_term_meta()
 

docs/api/inc/term-sidebars.rst

@@ -7,7 +7,11 @@ inc/term-sidebars.php
 
    .. php:method:: Largo_Term_Sidebars::display_fields()
 
-      Renders the form fields on the term edit page
+      Renders the form fields on the term's edit page
+
+   .. php:method:: Largo_Term_Sidebars::display_add_new_field()
+
+      Renders the form fields for the new form creation on the term listing paga
 
    .. php:method:: Largo_Term_Sidebars::admin_enqueue_scripts()
 

docs/api/inc/update.rst

@@ -22,7 +22,7 @@ inc/update.php
 
    :since: 0.3
 
-   :returns: boolean $f updates need to be run
+   :returns: boolean $result True if updates need to be run
 
 .. php:function:: largo_home_transition()
 
@@ -75,21 +75,21 @@ inc/update.php
 
    :since: 0.4
 
-   :returns: bool $f series were enabled by this function
+   :returns: boolean $result True if series were enabled by this function
 
 .. php:function:: largo_enable_series_if_landing_page()
 
    Enable the series taxonomy if the series landing pages are in use.
 
    :since: 0.4
 
-   :returns: bool $f series landing pages (and series) were enabled by this function.
+   :returns: boolean $result If series landing pages (and series) were enabled by this function.
 
 .. php:function:: largo_remove_topstory_prominence_term()
 
    Remove "top-story" prominence term to avoid conflicts with homepages that will register it
 
-   :returns: array $f deleted prominence terms
+   :returns: array $results Deleted prominence terms
 
 .. php:function:: largo_set_new_option_defaults()
 
@@ -125,13 +125,25 @@ inc/update.php
 
    :since: 0.5.3
 
+.. php:function:: largo_deprecated_callback_largo_featured()
+
+   Callback for updating the Largo Featured widget in largo_replace_deprecated_widgets()
+
+   :since: 0.5.3
+
+   :see: largo_replace_deprecated_widgets
+   :param array $deprecated: the deprecated widget's $instance variables
+   :param array $replacement: the replacement widget's $instance variables
+
+   :returns: array $result the replacement widget's $instance variables
+
 .. php:function:: largo_widget_in_region()
 
    Checks to see if a given widget is in a given region already
 
    :since: 0.5.2
 
-   :returns: bool $hether or not the widget was found.
+   :returns: boolean $result Whether or not the widget was found.
 
 .. php:function:: largo_instantiate_widget()
 
@@ -140,11 +152,11 @@ inc/update.php
    if $instance_settings are wrong, bad things might happen
 
    :since: 0.5
-   :param String $kind.: Kind of widget to instantiate.
-   :param Array $instance_settings.: Settings for that array.
-   :param String $region.: Sidebar region to add to.
+   :param string $kind.: Kind of widget to instantiate.
+   :param array $instance_settings.: Settings for that array.
+   :param string $region.: Sidebar region to add to.
 
-   :returns: Array $'id' => the id with number of the new widget , 'place' => the index of the id in its region )
+   :returns: array $result array('id' => the id with number of the new widget , 'place' => the index of the id in its region )
 
 .. php:function:: largo_get_widget_basename()
 

docs/api/inc/widgets/largo-author-bio.rst

@@ -0,0 +1,10 @@
+inc/widgets/largo-author-bio.php
+================================
+
+.. php:class:: largo_author_widget
+
+      Author Bio Widget
+
+      archive.php uses this widget to create the header of the Author Archive page
+
+      :package: Largo

docs/api/index.rst

@@ -35,6 +35,7 @@ Function reference by file
 * `inc/verify.php <inc/verify.html>`_
 * `inc/widgets.php <inc/widgets.html>`_
 * `inc/customizer/customizer.php <inc/customizer/customizer.html>`_
+* `inc/widgets/largo-author-bio.php <inc/widgets/largo-author-bio.html>`_
 * `inc/widgets/largo-facebook.php <inc/widgets/largo-facebook.html>`_
 * `inc/widgets/largo-image-widget.php <inc/widgets/largo-image-widget.html>`_
 * `inc/widgets/largo-post-series-links.php <inc/widgets/largo-post-series-links.html>`_

inc/enqueue.php

@@ -123,8 +123,9 @@ function largo_enqueue_admin_scripts() {
 	/**
 	 * Determine which size of the banner image to load based on the window width
 	 *
+	 * TODO: this should probably use picturefill for this instead
+	 *
 	 * @since 1.0
-	 * @todo: should probably use picturefill for this instead
 	 */
 	function largo_header_js() { ?>
 		<script>

inc/post-templates.php

@@ -111,7 +111,7 @@ function is_post_template( $template = '' ) {
  * The changes to the content in this function should eventually be made
  * perminant in the database. (@see https://github.com/INN/Largo/issues/354)
  * 
- * @since v0.4
+ * @since 0.4
  * 
  * @param String $content the post content passed in by WordPress filter
  * @return String filtered post content.
@@ -198,7 +198,7 @@ function largo_remove_hero($content) {
  * Retrieves the attachment ID from the file URL
  * (or that of any thumbnail image)
  * 
- * @since v0.4
+ * @since 0.4
  * @see https://pippinsplugins.com/retrieve-attachment-id-from-image-url/
  * 
  * @return Int ID of post attachment (or false if not found)

inc/term-meta.php

@@ -21,10 +21,9 @@ function largo_register_term_meta_post_type() {
 /**
  * Get the proxy post for a term
  *
- * @param string $taxnomy
- * @param int $term_id
- *
- * @return int $post_id
+ * @param string $taxnomy The taxonomy of the term for which you want to retrieve a term meta post
+ * @param int $term_id The ID of the term
+ * @return int $post_id The ID of the term meta post
  */
 function largo_get_term_meta_post( $taxonomy, $term_id ) {
 	$query = new WP_Query( array(

inc/update.php

@@ -71,7 +71,7 @@ function largo_version() {
  *
  * @since 0.3
  *
- * @return boolean if updates need to be run
+ * @return boolean $result True if updates need to be run
  */
 function largo_need_updates() {
 	// try to figure out which versions of the options are stored. Implemented in 0.3
@@ -394,7 +394,7 @@ function largo_force_settings_update() {
  *
  * @since 0.4
  *
- * @return bool If series were enabled by this function
+ * @return boolean $result True if series were enabled by this function
  */
 function largo_enable_if_series() {
 	// assuming that some posts will be in a series if series were used
@@ -416,7 +416,7 @@ function largo_enable_if_series() {
  *
  * @since 0.4
  *
- * @return bool If series landing pages (and series) were enabled by this function.
+ * @return boolean $result If series landing pages (and series) were enabled by this function.
  */
 function largo_enable_series_if_landing_page() {
 
@@ -448,7 +448,7 @@ function largo_enable_series_if_landing_page() {
 /**
  * Remove "top-story" prominence term to avoid conflicts with homepages that will register it
  *
- * @return array of deleted prominence terms
+ * @return array $results Deleted prominence terms
  */
 function largo_remove_topstory_prominence_term() {
 	$terms = get_terms('prominence', array(
@@ -720,7 +720,7 @@ function largo_replace_deprecated_widgets() {
  * @see largo_replace_deprecated_widgets
  * @param array $deprecated the deprecated widget's $instance variables
  * @param array $replacement the replacement widget's $instance variables
- * @return array the replacement widget's $instance variables
+ * @return array $result the replacement widget's $instance variables
  */
 function largo_deprecated_callback_largo_featured($deprecated, $replacement) {
 	if ( isset($deprecated['thumb'] ) ) {
@@ -737,7 +737,7 @@ function largo_deprecated_callback_largo_featured($deprecated, $replacement) {
  * Checks to see if a given widget is in a given region already
  *
  * @since 0.5.2
- * @return bool Whether or not the widget was found.
+ * @return boolean $result Whether or not the widget was found.
  */
 function largo_widget_in_region( $widget_name, $region = 'article-bottom' ) {
 
@@ -759,10 +759,10 @@ function largo_widget_in_region( $widget_name, $region = 'article-bottom' ) {
  *
  * @since 0.5
  *
- * @param String $kind. Kind of widget to instantiate.
- * @param Array $instance_settings. Settings for that array.
- * @param String $region. Sidebar region to add to.
- * @return Array ('id' => the id with number of the new widget , 'place' => the index of the id in its region )
+ * @param string $kind. Kind of widget to instantiate.
+ * @param array $instance_settings. Settings for that array.
+ * @param string $region. Sidebar region to add to.
+ * @return array $result array('id' => the id with number of the new widget , 'place' => the index of the id in its region )
  */
 function largo_instantiate_widget( $kind, $instance_settings, $region ) {