Forms API & other big array documentation
merlinofchaos - November 30, 2006 - 19:11
| Project: | API |
| Version: | HEAD |
| Component: | Code |
| Category: | feature request |
| Priority: | normal |
| Assigned: | moshe weitzman |
| Status: | active |
Jump to:
Description
We desperately need to be able to document forms api in API.module. And as we move forward, the new nodeapi stuff is going to need this sort of documentation as well.
I believe we need a way to document that's similar to our existing hook structure. But instead of using functions, we use something that isn't exactly PHP code
Something like?
<?php
/**
* Control the size of a Forms API widget.
*
* has meaning for: textfield, textarea, foo
*/
$api_key = "#size";
?>Note: this is just a napkin drawing, so to speak. I haven't thought this through, but I'd like to get some discussion going on this, because I see the difficulty in documenting forms API and other API like it to be a very serious impediment to developing Drupal. I'm constantly forgetting specifics and have to look in code to figure stuff out. That shouldn't be the answer we give people.
#1
I would say a more generic "big array structure" documentation is needed. Links, forms, menus, etc, are all big arrays.
#2
I had a inspiration on this - Lets define FAPI properties and elements in .info files. Each element gets a file where it describes self and points to an "example function" which demonstrates its use. Below are example .info files. I think this gives us all the data we need to to substantially recreate http://api.drupal.org/?q=api/file/developer/topics/forms_api_reference.html. We just need some PHP to glue it all together. The "example function" pointer isn't perfect, but it does is always up to date which is a huge plus. I think this system is extraordinarily easy to maintain.
name = radiosdescription = "Format a set of radio buttons."
example = "comment_controls"
And now a property:
name = #optionsdescription = Selectable options for a form element that allows multiple choices.
elements[] = radios
elements[] = checkboxes
elements[] = select
values = "An array in the form of array(t('Display value 1'), t('Display value 2')) or array('return_value1' => t('Display Value 1'), 'return_value2' => t('Display Value 2')) if specific return values are required."
example = "comment_form"
#3
@Moshe - hmm, perhaps instead it should move more to being like the hooks documentation where you can just write comments and sample code? The example above looks about as hard to maintain as the current HTML.
#4
I thought about that but we'd either have to invent a new doc syntax or shoehorn elements and properties into function definitions like element_textfield() and use standard doxygen above that. it gets even weirder for documenting properties.
I don't agree that maintaining the .info files is as hard as the big HTML doc. i think adding a new element or property will be far easier in the model where we just add a new small file. I hate messing with the huge HTML doc because I can break its structure. I think it is pretty clear that the community agrees with me because that HTML file is ugly stepchild who is barely looked after. Further, my proposed new page will use theme('table') for the element+property matrix and so will look more consistent with the rest of the site.
#5
Ok, I agree 100% we need a different process than the current one.
#6
Cool ... even if we invent a new syntax for documenting elements and properties inline, I have no clue how we implement the matrix and show which properties are valid for which elements. I think the array features of .info files are great match here.
#7
I haven't gotten to this level of thinking about the parser yet. The whole documentation parser is being rewritten in the next few weeks. The first step, breaking code into constants, functions, etc, is at http://drupal.org/node/300031. I will do a proper writeup of the whole process in the next few days.
These giant arrays have some similarities to objects, http://jaspan.com/dx-files-abandon-anonymous-arrays-attributes. Maybe we can document arrays as if they were objects
<?php
/**
* A form element.
*
* Apparently codefilter has a spacing bug here, this comment is spaced correctly in code.
*/
$form_element = array(
/**
* The type of the form element, can be radios, checkboxes, textfield, textarea, ....
*/
'#type' => 'radios',
/**
* The element's default value.
*/
'#default-value' => '...'
);
?>
Or maybe we need to make it easy to make tables in existing documentation comments. Doxygen does not appear to define a way to do this. There is a precedent with list building from lines starting with dashes.
#8
#9
@drumm - from your comment, I'm going to assume you are not especially interested in pursuing the .info file solution. Thats a bit sad, since this issue has API module has been waiting for a solution for this since 4.7. If I understand you wrong, let me know. I'm not qualified to implement the parser based solution. Nor do I know how that gets us a matrix based on the individual docblocks.
#10
I think .info files needs more thought and maybe examples. I don't think they area bad idea, but I'm not sure how good they are yet. The info files are a new use of that syntax to learn.
A couple questions:
What would the ideal Form API and other big array documentation look like? Is what we have on the site good or can we do better?
API documentation is maintained and relevant because it is in-code. How can we document big arrays as close to the code as possible with easy syntax?
#11
subscribing. I need more time to digest and get my head to thinking about this before I speak up. I do agree we need something better than what have though. :-)
#12
HAH! You want unintelligible and unmaintainable? Doxygen! http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/panels/pane... . The stuff in that ALIASES definition is what's used to build http://doxy.samboyer.org/panels2/panels_api_plugins_content_types.html, which I think is quite analogous to the forms api reference. At least, I intended it to be when I wrote it. Bottom line, I raise this as what I hope is an example of why really need a system for this (the automated hot interlinking with functions definitions laced throughout that page is CRUCIAL to it being remotely useful) but also as an example of what we really, really must avoid in order to get there. The source doc that generates that output, btw, is here: http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/panels/docs...
Anyway, to say something more substantive. There are a few approaches to solutions to this that I can think of, but it's also not totally clear to me what the goal is here. So I'm a touch lost. Are we just trying to implement a system for reproducing the current page that's in HTML? Or do we want something richer - say, such that API docs could automagically turn instances of these big array properties in sample code into links pointing back to documentation on that form item? To be sure, such a thing would be easier if we were to switch over to explicitly using classes for this stuff...but it's far from impossible now.
#13
The parsing architecture I am working toward is:
1. Split file into documentation comment & code pairs.
2. Parse documentation comment into a data structure.
3. Save.
The form API documentation should be in a format that can cleanly go through step 1, either PHP code, specialized HTML or something else. Globals documentation set a precedent for documenting not-exactly-standard PHP, http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/glob.... The same convention can be built up around arrays and other PHP documentation.
Once step 2 is improved, it should be doable to add more @tags. @tags might be added for form documentation.
As always, everything should be as generally useful as possible, a specialized form API hodgepodge would not be good.
The slow option is to wait until API module handles objects (weeks) and form API is fully object-based (years).