Allow type definitions for parameters and returns
| Project: | API |
| Version: | 6.x-1.x-dev |
| Component: | Parser |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | active |
Jump to:
Drupal's docblock format is derived from Doxygen. Doxygen was designed for C++ and other strongly typed languages, where specifying the type of a given parameter or return value was redundant since it was always specified in the language itself.
That is not the case in PHP. In PHP, you don't know what type you're dealing with unless you specify that explicitly in documentation. PHPDoc, therefore, includes the following format for docblocks:
<?php
/**
* Short description here.
*
* @param string $myvar
* Description of $myvar here.
* @return int
* Description of the meaning of the return value here.
*/
?>We should do the same, and optionally allow type definitions on both params and return.
Why?
For one, nearly all code completion tools for PHP auto-generate such values where known so we're getting them in contrib anyway, and even some core docblocks have them. We may as well allow them explicitly and ensure that nothing breaks.
For another, while you can in PHP 5 specify a class or interface type explicitly in the function signature to indicate that the value MUST be of that type (and it's a fatal error if not), that doesn't do anything for return types. However, when dealing with OO code (which Drupal is starting to do a fair bit of between Views, DBTNG, the new update system, and various others) it much much nicer to be able to specify a return value type. Many IDEs can detect that information and then code-complete a returned object dynamically. That is, if I call db_query(), and it's documented to return an object of type DatabaseStatementInterface, then I can type db_query()-> and get all of my possible fetch methods listed for me. That's extremely useful.
Even for parameters there is a benefit. While PHP can specify a type in the method signature, when inheriting methods you sometimes don't want to enforce that because the child method will need a different interface than the parent; specifically an interface that is extended from the interface specified in the parent. Doing that breaks (It's E_STRICT invalid at the very least), so you can't do so in the actual method signature. You can, however, specify the exact type you want for that subclass in the docblock for a method without breaking the parser.
Even if this information is not displayed in the API docs, we should make sure that api.module doesn't choke on type information when it's provided and handles it gracefully.
#1
subscribing
#2
Hell yes!
#3
+1
#4
Better quality documentation at the cost of maybe a parser bug or two... seems like an easy win.
The only really special case I can think of is specific Object types (Interfaces, etc.), which could be turned into links.
#5
Yes, automatically linking types would be neat. I'm happy for that to be a phase 2 though, as long as we can start entering them into code. I'd love to go through DBTNG and just add a whole bunch of documentation.
#6
I already do this, and kinda look down on code that doesn't - at least, if they do doc parameters, but don't indicate type. And it's even more extra-super useful, as Crell pointed out in the OP, if you specify object types.
Massive +1.