OOPHP_02.book Page 129 Friday, May 5, 2006 2:25 PM
Fortunately, ReflectionMethod and ReflectionProperty also have getDocComment methods, so method-level and data member–level comments can also be included. NOTE
Those of you familiar with PEAR (PHP Extension and Application Repository) and phpDocumentor or the Java utility Javadoc will already know the proper format for internal comments.
ReflectionMethod and ReflectionParameter ReflectionMethod objects contain all the information you need to fully describe
a method. By using this object you can document the modifiers of a method; you can use its getParameters method to return an array of ReflectionParameter objects, which is essential for describing a method’s parameters. A ReflectionParameter object will give you the number of parameters, their names, and any default values. You can even determine whether a parameter is a specific type of object if it is type hinted—yet another good reason to use type hinting. There is one respect in which you might find the ReflectionMethod class wanting, however. Sometimes it’s important to know what a method returns; for example, when using the getMethods method, it is essential to know that an array of ReflectionMethod objects is returned. Since you can type hint parameters and retrieve this information it would be nice to do the same with returned values. However, because PHP is a weakly-typed language, it’s not surprising that this capability is not supported, so be sure to document return types in your comments where appropriate. NOTE
Type hinting return values is planned for PHP 6, so perhaps we can expect support for this capability in future versions of the reflection classes. ReflectionProperty The getProperties method of ReflectionClass is similar to the getMethods method. It returns an array of ReflectionProperty objects that can be queried in much the same way as ReflectionMethod objects. (Determining whether default values exist for data members poses some challenges; more about this shortly.)
Built-in Functions We’ve looked at the principal classes and methods of the reflection classes, but there are some built-in PHP functions that can also be helpful when documenting classes. Most of the functions in the Class/Object group have been effectively, if not explicitly, deprecated in PHP 5 precisely because there are now reflection classes that do a superior job. However, a number of functions, such as get_declared_classes and is_object, continue to be useful.
C r eat in g D ocu me nt a ti on Us in g th e R ef le ct ion C l as s es
129