Add missing type hinting to Poll module docblocks

Thanks @bleen18 for rolling this and the other type hinting patches. If you have a chance, perhaps you could try updating the patch in #1800330: Add missing type hinting to System module docblocks. That one has a bunch of review comments from @jhodgdon.

Re: #2 Look at #1487760: [policy, no patch] Decide on documentation standards for namespaced items for discussion about our new standard for name-spacing. I have seen several patches that use this new standard. As a result, from afar, I believe the following is the proper documentation:

- * @param $node
+ * @param \Drupal\node\Node $node

I will try to get to reviewing this and the other type hinting patches you have created later this weekend. In the interim, I have some personal life commitments to meet.

Thanks for the patch @bleen18. Here is a purposefully nit-picking review along with comments in dreditor so that whoever commits this eventually can see what was checked.

One thing I noticed that was common throughout this patch was no leading slash '\' ahead of 'Drupal\node\Node' type hints in the docblocks. The policy for this was recently adopted in #1487760: [policy, no patch] Decide on documentation standards for namespaced items. As a result, you might want to do a global replace for those string occurrences within docblocks.

+++ b/core/modules/poll/poll.moduleundefined
@@ -107,11 +107,11 @@ function poll_menu() {
  *
- * @param $node
+ * @param Drupal\node\Node $node
  *   The poll node object.

I am not sure about this type hint. My suspicion is that a stdClass object is sufficient here since no Node methods are used in this function. Hence, I would change it object.

If it were to remain 'Drupal\node\Node', it needs to start with a '\'.

+++ b/core/modules/poll/poll.moduleundefined
@@ -107,11 +107,11 @@ function poll_menu() {
- * @param $perm
+ * @param string $perm
  *   A permission the user must have to view the page.
- * @param $inspect_allowvotes
+ * @param bool $inspect_allowvotes
  *   TRUE if the user can view votes, and FALSE if the user cannot view votes.
  */
 function _poll_menu_access($node, $perm, $inspect_allowvotes) {
@@ -620,11 +620,13 @@ function poll_delete($node) {

These two type hint additions to _poll_menu_access() are correct.

+++ b/core/modules/poll/poll.moduleundefined
@@ -620,11 +620,13 @@ function poll_delete($node) {
  *
  * @param Drupal\node\Node $node
  *   The node entity to load.

This type hint needs to start with a leading '\'.

+++ b/core/modules/poll/poll.moduleundefined
@@ -620,11 +620,13 @@ function poll_delete($node) {
+ * @return Drupal\node\Node $node

Thanks for adding this missing @return directive. It needs a leading slash '\' and a explanation line.

+++ b/core/modules/poll/poll.moduleundefined
@@ -690,10 +692,10 @@ function poll_view($node, $view_mode) {
  *
- * @param $node
+ * @param Drupal\node\Node $node
  *   The poll node object.
  *
- * @return
+ * @return string
  *   Poll choices in a simple teaser format.

This docblock needs some work. Again I think this can be a simple object as long as it contains the 'choice property. Hence, I would change the first type hint to object.

The second type hint should be 'string|null' since NULL can be returned.

+++ b/core/modules/poll/poll.moduleundefined
@@ -711,11 +713,12 @@ function poll_teaser($node) {
  * Form constructor for the poll voting form.
  *
- * @param $node

As above, I think that this type hint should be 'object' instead of a full Node object.

+++ b/core/modules/poll/poll.moduleundefined
@@ -834,6 +837,17 @@ function template_preprocess_poll_vote(&$variables) {
  *
+ * @param Drupal\node\Node $node
+ *   The poll node whose results are to be displayed.
+ * @param string $view_mode
+ *   The view mode to use when displaying the poll results.
+ * @param bool $block
+ *   (optional) TRUE if a poll should be displayed in a block. Defaults to
+ *   FALSE.
+ *
+ * @return string
+ *   The themed poll results.

Thanks for adding these missing @param and @return directives and explanations. They are correct except that the first one needs a leading slash '\'.

+++ b/core/modules/poll/poll.moduleundefined
@@ -877,7 +891,7 @@ function poll_view_results($node, $view_mode, $block = FALSE) {
  *
- * @param $variables
+ * @param array $variables
  *   An associative array containing:

This type hint addition is correct in theme_poll_choices().

+++ b/core/modules/poll/poll.moduleundefined
@@ -931,7 +945,7 @@ function theme_poll_choices($variables) {
  *
- * @param $variables
+ * @param array $variables
  *   An associative array containing:

This type hint addition is correct in template_preprocess_poll_results().

+++ b/core/modules/poll/poll.moduleundefined
@@ -960,7 +974,7 @@ function template_preprocess_poll_results(&$variables) {
  *
- * @param $nid
+ * @param int $nid
  *   The poll node ID.

This type hint addition for poll_cancel_form() is correct.

+++ b/core/modules/poll/poll.pages.incundefined
@@ -8,7 +8,7 @@
  *
- * @return
+ * @return string
  *   The HTML for the page that shows the available polls.

This type hint addition for poll_page() is correct.

+++ b/core/modules/poll/poll.pages.incundefined
@@ -56,10 +56,10 @@ function poll_page() {
  *
- * @param $node
+ * @param Drupal\node\Node $node
  *   The poll node object.
  *
- * @return
+ * @return array
  *   Render array containing table with votes.

These added type hints for poll_votes() are basically correct. The first one needs a leading slash '\'.

I would change the second explanation to 'A render array containing a table with votes.'

+++ b/core/modules/poll/poll.pages.incundefined
@@ -110,10 +110,10 @@ function poll_votes($node) {
  *
- * @param $node
+ * @param Drupal\node\Node $node
  *   The poll node object.
  *
- * @return
+ * @return array
  *   An array suitable for use by drupal_render().

The type hints added for poll_results() are again basically correct. However, the first again needs a leading slash '\'.

========== Additional review notes:

I noticed too that we are missing a @return directive for _poll_menu_access().

It appears that all of the @param and @return directive is missing for _poll_choice_form(). Remember to use '(optional)' and 'Defaults to x' in the explanation of each of the variables with a default value.

I am not sure whether or not we need @param and @return directives for poll_node_form_submit(). What do you think? Perhaps it might be better to change the one line summary to 'Form submission handler for node_form().' In that case, no @param directives are required according to doc standards.

Both poll_preprocess_block() and template_preprocess_poll_vote() need a @param directive like that used in template_preprocess_poll_results().

Checking the rest of the files for the Poll module, I see that we have missid two @return type hints in PollTestBase.php.

Thanks again for rolling this patch @bleen18. I could easily roll a patch that includes these changes. However, that would preclude me from reviewing the results. Could you address what I have noted above and then I will review it so that it is in pristine condition for @jhodgdon's final review and commit? Thanks in advance.

Just to note for cross-reference... Issue #1355712-45: Clean up API docs for Poll Module has notes about missing @param and/or @return directives for the Poll module. We need to double-check that we have caught here all of the @param/@return items noted there.

Thanks @bleen18. Could you possibly add an interdiff between #6 and #1? It really would help when reviewing these detailed documentation patches. Thanks a lot!

(I am working on a detailed review of Overlay sub-issue right now and am almost done with that one. I will try to come back to this one after that.)