ZF-7417: clarify confusion between 'resource plugins' and 'resources' in docs

Description

This issue was spawned from this forum question: http://nabble.com/confusion-between-resource-plugiā€¦

The Problem By reading the ZF Docs for Zend_Controller and Zend_View, the reader is habituated into a more pedantic mode of thought. That is, we learn that the terms to describe objects are very specific.

  • An 'action controller' is very different to a 'front controller' which is different to a 'controller plugin' which is very different to a 'controller helper'
  • A 'View' is very different to a 'view helper'

However, the documentation for Zend Application is written in a slightly less pedantic way:

Under section "4.3.2. Resource Plugins" It says: "Resources need only implement Zend_Application_Resource_Resource, or, more simply still, extend Zend_Application_Resource_ResourceAbstract. "

Under section "4.4. Examples" It says:

"Resource plugins implement Zend_Application_Bootstrap_Resource, which defines simply that they allow injection of the caller and options, and that they have an init() method. "

Note: * that the words 'Resources' and 'Resource plugins' are used interchangeably to mean the same thing. * there is a typo in the second paragraph: 'Zend_Application_Bootstrap_Resource' should be 'Zend_Application_Resource_Resource' - (issue ticket for typo already is submitted @ ZF-7416 ).

--

Now imagine a newbie coming to the Zend Framework and reading the documentation on Zend_Application before they read the Zend_Controller (which seems quite likely these days). Instead they will be habituated to read the docs in a less pedantic way.

So, if there is no consistency in the language used to describe a 'resource plugin' or 'resource' within the Zend_Application docs...it will lead to even more confusion when the reader arrives at Zend_Controller and starts learning about 'controllers' and 'controller plugins'.

Just my thoughts.

Comments

Worth being aware of the two issues : * Typo * improvement to docs

to make 'find and replace' go smoothly.

Language updated and made more consistent. Fixes applied to trunk and 1.9 release branch.