PHP Objects, Patterns and Practice (3rd edition)

CHAPTER 16 ■ GENERATING DOCUMENTATION WITH PHPDOCUMENTOR

Figure 16–5. Documenting properties

Documenting Methods

Together with classes, methods lie at the heart of a documentation project. At the very least, readers
need to understand the arguments to a method, the operation performed, and its return value.
As with class-level DocBlock comments, method documentation should consist of two blocks of
text: a one-line summary and an optional description. You can provide information about each
argument to the method with the @param tag. Each @param tag should begin a new line and should be
followed by the argument name, its type, and a short description.
Because PHP does not constrain return types, it is particularly important to document the value a
method returns. You can do this with the @return tag. @return should begin a new line and should be
followed by the return value’s type and a short description. I put these elements together here:

/**

• Perform the key operation encapsulated by the class.


• Command classes encapsulate a single operation. They


• are easy to add to and remove from a project, can be


• stored after instantiation and execute() invoked at


• leisure.


• @param $context CommandContext Shared contextual data


• @return bool false on failure, true on success
  */