Sometimes docblocks do not stick with their method.

[aubreypwd]

Docblocks sometimes get moved to the top of the class. The only pattern I see is that the comments that don't stick use @throws at the end? Right now it's not a big deal to just move them back to their methods, but I imagine this could be fixed.

Here's an example of a docblocks that got moved to the top of the class when I used this.

	/**
	 * Add a group.
	 *
	 * @param array  $args {
	 *     Arguments (type and name must be a unique combination and sanitized with sanitize_title_with_dashes()).
	 *     @type string $type  (Required) The group type (must be sanitized with sanitize_title_with_dashes() prior).
	 *                                    You cannot use an unregistered group type here.
	 *     @type string $name  (Required) The static name of the group (does not change in the database, must be sanitized with sanitize_title_with_dashes() prior).
	 *     @type string $title (Required) The title of the group (can be changed later with `self::update`, unlike `name`).
	 *     @type array  $meta  (Must be an array) Additional information about the Group.
	 * }
	 * @param string $return What to return, `id` (default) for the group's `group_id` value in the database,
	 *                       or `object` for a `\AffiliateWP\Groups\Group`.
	 *
	 * @return int|\AffiliateWP\Groups\Group|WP_Error `WP_Error` if we were unable to add the group to the database.
	 *                                                `WP_Error` if you try to add a group to an unregistered group type.
	 *                                                `WP_Error` if you include `group_id` in your arguments.
	 *                                                If `$return` is set to `id` (default), and we were able to add the group, the `group_id` of the group from the database.
	 *                                                If `$return` is set to `object`, a `\AffiliateWP\Groups\Group` instance for the added group in the database.
	 *
	 * @throws \InvalidArgumentException              If `$args` is not an `array`.
	 *                                                If `$return` is not a `string` and is not set to either `id` or `object`.
	 */

	/**
	 * Get groups from the database.
	 *
	 * @param  array $args {
	 *
	 *     Arguments for getting a list of groups (ids or objects).
	 *
	 *     @type string $fields  Set to `ids` to get back an array of group ids (group_id column) from the database (default).
	 *                           Set to `objects` to get a list of `\AffiliateWP\Groups\Group` objects.
	 *
	 *     @type int $group_id   When set to a positive numeric value, we will only give you a single group when this is set.
	 *                           Setting `fields` to `ids` here would be silly if you already have the id.
	 *
	 *     @type int $number     Used to set `LIMIT` and limit the number of groups handed back.
	 *     @type int $offset     Used to set `OFFSET` and used to offset query.
	 *
	 *     @type string $orderby Used to set `ORDER BY` and should be a valid column in the groups database table.
	 *                           If you supply a column that doesn't exist in our database, you will get back empty results.
	 *                           If you do not supply anything, the default is `group_id`.
	 *
	 *     @type string $order   Used to set `ORDER` and accepts `ASC` or `DESC`.
	 *                           If you do not supply these, we will always default to `ASC`.
	 *
	 *     @type string $type    Used to set `WHERE type = %s` and will help you return groups grouped by a specific group type.
	 *                           Note, does not restrict you to registered group types or enforce sanitization beforehand.
	 * }
	 *
	 * @param  bool  $count      Set to `true` to just get the number of result.
	 *
	 * @return array|WP_Error    An `array` of `\AffiliateWP\Groups\Group` objects if `$args[fields]` is not set to `ids`.
	 *                           An `array` of group ids (`group_id` in the database).
	 *                           A `WP_Error` if there is a problem with your arguments.
	 *                           A `WP_Error` if there are unexpected DB results.
	 *                           The number of groups in the database if `$count` is set to `true`.
	 *
	 * @throws \InvalidArgumentException If `$args` is not an array.
	 *                                   If `$count` is not `true` or `false`.
	 */

	/**
	 * Get a group's id (group_id) from the database.
	 *
	 * You can use a `type` and `name` (columns in the database) to retrive an value for `group_id`
	 * from the database.
	 *
	 * @param array $args {
	 *     Arguments for attempting to get `group_id` by unique `name` and `type` commbination.
	 *
	 *     @type string $type (Requred) The value for `type` column in the database.
	 *     @type string $name (Requred) The value for `name` column in the database.
	 * }
	 *
	 * @return int|bool|WP_Error The `group_id` (int) value of the group in the database if it is found by `name` and `type`.
	 *                           `false` if a group was not found by that `name` and `type`.
	 *                           `WP_Error` if your arguments are not properly configured (`type` and `name` must be set and be non-empty strings).
	 *                           `WP_Error` if there was an issue finding the `group_id` in the database (other than not being found).
	 *
	 * @throws \InvalidArgumentException If `$args` is not an array.
	 */

	/**
	 * Register a group type.
	 *
	 * Group types are used for setting the `type` column in the database.
	 * This method also stores global information about the type.
	 *
	 * If you try to add a new group with a type that isn't registered, you can't.
	 *
	 * @param string $type The group type (must be sanitized with `santize_title_with_dashes()` prior).
	 *
	 * @param array  $args   {
	 *
	 *     Arguments for registering group types.
	 *
	 *     @type string $title The title of the group (not required, not yet used).
	 * }
	 *
	 * @return bool|WP_Error `true` if we registered it successfully.
	 *                       `false` if it's already registered.
	 *                       `WP_Error` if there is an issue with your arguments.
	 *
	 * @throws \InvalidArgumentException  If `$args` is not an `array`.
	 *                                    If `$type` is not a `string` or is empty.
	 */

	/**
	 * Update a group in the database.
	 *
	 * @since [-NEXT-]
	 *
	 * @param int   $group_id The value for `group_id` in the database.
	 *
	 * @param array $args {
	 *
	 *     Arguments for updating a group. Set either to null to skip updating (or do not set).
	 *
	 *     @type string $title A value to update the title to.
	 *     @type array  $meta  A value to update the meta to.
	 * }
	 *
	 * @return bool|WP_Error `true` if data was actually changed, `false` if nothing was changed (was same data).
	 *                       `WP_Error` if there was an issue with your arguments.
	 *                       `WP_Error` if the group doesn't exist.
	 *
	 * @throws \InvalidArgumentException If you pass invalid parameters.
	 */

	/**
	 * Get the number of groups in the database.
	 *
	 * @param array $args {
	 *     Arguments.
	 *
	 *     @type string $type Require `type` column to be this value in the database.
	 * }
	 *
	 * @return int                       The number of rows counted in the database.
	 * @throws \InvalidArgumentException If `$args` is not an array.
	 */

[foxxyz]

Do you have a small example of a file where this happens that I can use as a test case?

[aubreypwd]

The file where this happened, I can't share unfortunately. But maybe I can try and replicate with my own code.

[foxxyz]

The file where this happened, I can't share unfortunately. But maybe I can try and replicate with my own code.

Yeah just a small file with fake content that exhibits the aforementioned behavior is fine.