6.0.0-alpha12
6/10/25

[#14512] revise library documentation
Summary revise library documentation
Queue Horde Framework Packages
Type Enhancement
State Rejected
Priority 1. Low
Owners
Requester birnbacs (at) gmail (dot) com
Created 11/11/2016 (3133 days ago)
Due
Updated 11/16/2016 (3128 days ago)
Assigned
Resolved 11/16/2016 (3128 days ago)
Milestone
Patch No

History
11/16/2016 08:45:18 AM Jan Schneider Comment #2
State ⇒ Rejected
Reply to this comment
Besides that documentation can always be improved, we are aware that 
documentation lacks in many places. No reason to track this in a ticket.
But more important: documentation is something that the community can 
easily contribute, without having too much development skills. The 
wiki is open to anyone.
11/11/2016 12:54:17 PM birnbacs (at) gmail (dot) com Comment #1
State ⇒ New
Priority ⇒ 1. Low
Type ⇒ Enhancement
Summary ⇒ revise library documentation
Queue ⇒ Horde Framework Packages
Milestone ⇒
Patch ⇒ No
Reply to this comment
Some of the libraries have incomplete or incorrect doumentation. 
Behaviour of some methods is therefore unclear or concealed.

Consider for example the Horde_Form library. One important method is 
to set the form's buttons. The docs say only this:

Horde_Form::setButtons         ( $submit,
                          $reset = false
        )

End of documentation. However, the method will digest an array of 
buttons and has extremely useful support for CSS classes so that this 
is possible:

     $myform->setButtons(array(
             array('class' => 'horde-delete', 'value' => _("Modify")),
             array('class' => 'horde-cancel', 'value' => _("Cancel")),
        ));


The above example is only one of probably several tens or even more 
than hundred. For many existing methods there is no way of telling 
what they do other than trying them out.

The low quality of the documentation is a major drag to any Horde 
programmer, especially the new folks. Telling a flawed documentation 
from a bug can also be difficult and takes a lot of effort from the 
programmer.



Saved Queries