[documentation] [Documentation bug] hook_validate documentation claims to use modifications to the passed $node parameter

[webchick]

Issue status update for 
http://drupal.org/node/101930
Post a follow up: 
http://drupal.org/project/comments/add/101930

 Project:      Documentation
 Version:      <none>
 Component:    Misc
 Category:     bug reports
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  Wesley Tanaka
 Updated by:   webchick
-Status:       closed
+Status:       patch (code needs work)

We have a problem...


The API docs should be about code as it *currently* stands. There
should be no references to Drupal versions past; information about API
quirks that changed between versions belongs in the "Converting your
modules" part of the handbook. Imagine how bloated the API docs would be
if we documented every time that an API changed between versions!


So could you please re-word these changes so they're not "Since Drupal
4.7..." and instead "You may not..." or whatever?




webchick



Previous comments:
------------------------------------------------------------------------

Thu, 07 Dec 2006 14:08:15 +0000 : Wesley Tanaka

http://api.drupal.org/api/4.7/function/hook_validate says:


"
It can also be used to make changes to the node before submission, such
as node-type-specific formatting.


"
Both my recollection and an attempt to do that just now are contrary to
that claim.




------------------------------------------------------------------------

Thu, 07 Dec 2006 14:13:07 +0000 : Wesley Tanaka

Ah yes, hook_submit does exist (I didn't see it the first time in the
list).  I'd suggest:


1. changing the hook_validate documentation so that the $node parameter
is no longer preceded with '&'
2. removing the claim that it's possible to make changes to the node
3. adding a reference to hook_submit for people that want to make
changes to a node.




------------------------------------------------------------------------

Sat, 16 Dec 2006 21:24:40 +0000 : plumbley

Attachment: http://drupal.org/files/issues/node.php_1.patch (1.35 KB)

+1 for this fix (remains in HEAD documentation). Combined with an out of
date node_example.module, I think this has been confusing quite a few
people for a while.


Patch for  HEAD attached. Please also apply to 4.7, since it is wrong
there too.


Best wishes,


Mark.




------------------------------------------------------------------------

Sun, 17 Dec 2006 17:07:19 +0000 : pwolanin

Attachment: http://drupal.org/files/issues/node.php_2.patch (1.79 KB)

I'm not sure the & symbol matters- it can be preferable to pass large
object by reference just for speed's sake. 


Also, in PHP5 all objects are passed by reference no matter the
declaration.


Also, the changes are not quite correct, since form_set_value() can be
used to make changes at the validate stage:


http://api.drupal.org/api/HEAD/function/form_set_value


Attached patch commited to HEAD version (FYI, anone with CVS access can
commit to the docs)




------------------------------------------------------------------------

Sun, 17 Dec 2006 17:10:03 +0000 : pwolanin

also commited the same changes to the 4.7 branch




------------------------------------------------------------------------

Sun, 17 Dec 2006 17:32:20 +0000 : plumbley

Minor follow up (no action)... Personally I do think removing the &
symbol (as in the applied patch) really does matter, since to have left
it in would strongly imply pass by reference. Since this is what was
true historically (Drupal 4.6), I think the documentation should use
belt and braces (comments and code) to make this change as clear as
possible.




------------------------------------------------------------------------

Mon, 18 Dec 2006 08:58:43 +0000 : Wesley Tanaka

Removing the & is important because it makes it clear that changes to
the parameter *cannot* be propogated outside of the function.


(in an unimportant but slightly relevant note: I remember chx posting
somewhere that parameters without the '&' are actually faster -- some
notice produced by his development tool, but I can't find that bug
trail).