[Tickets #14512] revise library documentation

[noreply at bugs.horde.org]

BITTE NICHT AUF DIESE NACHRICHT ANTWORTEN. NACHRICHTEN AN DIESE  
E-MAIL-ADRESSE WERDEN NICHT GELESEN.

Ticket-URL: https://bugs.horde.org/ticket/14512
------------------------------------------------------------------------------
  Ticket           | 14512
  Erstellt Von     | birnbacs at gmail.com
  Zusammenfassung  | revise library documentation
  Warteschlange    | Horde Framework Packages
  Typ              | Enhancement
  Status           | New
  Priorität        | 1. Low
  Milestone        |
  Patch            |
  Zuständige       |
------------------------------------------------------------------------------


birnbacs at gmail.com (2016-11-11 12:54) hat geschrieben:

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.