Part of meta-issue #1310084: [meta] API documentation cleanup sprint and continuation of #1313510: Clean up API docs for statistics module.

This issue is focused on further changes to bring Statistics module closer to D8/D7 documentation standards. This issue, for instance, will ensure that there are no missing @param or @return directives from docblocks and that the various Test files are in accord with http://drupal.org/node/1354. It also will ensure that one missing @file directive is corrected.

CommentFileSizeAuthor
#1 1812008-1-statistics-docs.patch6.13 KBlars toomre

Comments

lars toomre’s picture

lars toomre commented
Status: Active » Needs review
StatusFileSize
new 1812008-1-statistics-docs.patch6.13 KB

Attached is an untested locally patch that is a result of reading through the top level of the current Statistics module from a documentation perspective.

The above review did not include a review of any of the Test files for this module.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs review » Needs work

Thanks! Most of this patch is good. A few issues:

a) This type change is not part of our official documentation standards and needs to be removed from the patch:

- * @ingroup forms
  * @see statistics_settings_form_submit().
+ *
+ * @ingroup forms

b)

+++ b/core/modules/statistics/statistics.pages.inc
@@ -11,8 +11,11 @@
  * Page callback: Displays statistics for a node.
  *
  * @return array
- *   A render array containing node statistics. If information for the node was
- *   not found, this will throw a NotFoundHttpException.
+ *   A render array containing node statistics.
+ *
+ * @throws Symfony\Component\HttpKernel\Exception\NotFoundHttpException
+ *   If information for the node was not found, this will throw a
+ *   NotFoundHttpException.

The @throws tage does not have a description with it, so there should not be indented information below it. Just put this information into a paragraph above the first @param.

lars toomre’s picture

lars toomre commented

Thanks for the review @jhodgdon. I will leave this to someone else to re-roll to address the issues raised in #2.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Issue summary: View changes
Status: Needs work » Closed (won't fix)

These issues are a lot of work with very little tangible payoff, so I'm closing the rest of them as "won't fix". Your efforts on working on this issue were appreciated... it was just my fault for starting a task that was very difficult to get right.

Let's instead put our effort into fixing and reviewing documentation that is really unclear and/or wrong, and I hope that the people who worked on these issues are not afraid to jump into a more reasonable issue!