[documentation] [bug] Incomplete documentation on hook_help

[fgm]

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

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     bug reports
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  fgm
 Updated by:   fgm
 Status:       active

It depends on what core developers think is the right fix to  bring:



* should the path on on admin/help#<modulename> be removed or
documented ?
* should the alternate path on admin/help/<modulename> be removed or
documented ?
* should the path on admin/help be removed or documented ?

because this makes for a different patch in each case, either to code
or to doc.


IMHO, (3) should be documented, (1) should be removed, and (2) should
be kept and replace (1) in the docs because, as this is a page all on
its own, it does not respect the usual "fragment" semantics, which are
supposed to access a part of a page /at the client side/ as the web
server is not supposed to receive it. See for instance:



* http://www.w3.org/DesignIssues/ModelConsequences
* http://www.w3.org/Addressing/URL/4_2_Fragments.html
* http://www.w3.org/2001/tag/doc/identify

However, drupal apparently makes heavy use of the fragment parts or
URLs (syntax (1)) so, for the sake of drupal's internal consistency,
and at the cost of consistency with the rest of the WWW, it could be
better to keep (1) instead of (2).




fgm



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

Sat, 10 Dec 2005 20:54:59 +0000 : fgm

The current API documentation for hook_help [1] says hook_help is called
with a $section parameter with a definite set of values, enumerated on
the page.


However hook_help is also invoked with at least two other non
documented values:



* from the admin/help page, the hook is invoked with $section ==
'admin/help'
* from the admin/help/<modulename> page, the hook is invoked twice:

* once with $section == 'admin/help#<modulename>' as documented
* once with $section == 'admin/help/<modulename>' which is not
documented



While the second invocation on admin/help/<modulename> seems redundant
and one of the calls might have to be removed or at least documented as
obsoleted, the ability for the hook to be fired from the main help page
is valuable in that it allows a module creator to insert documentation
in the main help page, so the doc should be amended to specify that
behaviour.


[1] http://drupaldocs.org/api/head/function/hook_help\" title=\"Drupal
hook_help API




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

Sun, 11 Dec 2005 02:16:15 +0000 : drewish

Would you mind posting a patch that begins to correct this? Having one
would make it easy to start a discussion.