> > It return false on failure as documented. I feel we should use this for all > > functions where any failure results in false. This way users easily know > > that they must check for func()!==false > > That's something to bring up for discussion but right > now it's not how we document functions. Only resource > should be listed there.
Right now, the quick fix should be: <type>resource</type>. <type>s in some contexts are used to create links to the types description page, and in some outputs in the future, we may want to make this too for function prototypes. Anyway, XML is designed to give structure to documents and not to enclose documents with their own structure specification. So if we want to add to a function that it has more then one return type, then we should not invent a new syntax for it, but try to find a DocBook solution or extend DocBook for this purpose. Please revert that type back to "resource". False is even not a type at all... > I like your idea of more structure. Right now each manual > entry is full of <notes>'s, parameter descriptions can > sometimes get lost, and what the function does on failure > is also not structured. During the phpdoc meeting awhile > back there was discussion of each manual entry having > a CHANGELOG but that's only part of it. > > Here's a rough example (it's late, forgive me): > > function in_array: > > -------------------------------------------------------------- > Parameter | Description | Notes > -------------------------------------------------------------- > needle | What is being searched for | Became mixed in > | | PHP 4.2.0 > haystack | What we're searching in | > strict | If set to true, the type will | Defaults to false > | also be compared. | > ============================================================== > On failure: returns false > -------------------------------------------------------------- > > Seeing that below the proto might be useful and easy to read. > Anyway, something to think about :) There are some functions somewhere in the documentation with parameters documented this way, but I cannot find them right now... This would be a very nice thing (TM) IMHO, but needs a tremendous amount of work and/or a very long time. We discussed the idea of restructuring the manual pages in a "man" like manner, to organize content... It would be quite nice, but I cannot volunteer any time to this project. Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
