ZF-3225: Add link to the service in the class docblock

Description

Although it is up to the developers to make sure that they are in compliance with the service's terms of use, it would be good to have a link to the service in the class docblock.

Comments

The codingstandard says that when a class extends or implements another class it MUST have a @uses clause.

The problem is where to link to ? The online manual ? As there is no BASE service class there is nothing which the developer must link to.

{quote}The codingstandard says that when a class extends or implements another class it MUST have a @uses clause.{quote}

Thomas, could you please provide a link to this assertion. I searched for it but I have been unable to find the paragraph.

About the link, when I created Zend_Service_Technorati I added a @link tag from each API method. For example


     * 
     * @param   string $url     the URL you are searching for. Prefixes http:// and www. are optional.
     * @param   array $options  additional parameters to refine your query
     * @return  Zend_Service_Technorati_CosmosResultSet
     * @throws  Zend_Service_Technorati_Exception
     * @link    http://technorati.com/developers/api/cosmos.html Technorati API: Cosmos Query reference
     */

Then I added a link to Technorati API in the official ZF documentation. Are you suggesting to add an additional @link tag in the class docblock pointing to Technorati API homepage?

An other question. Is there any reason for including Zend_Service_Server in the component list for this ticket?

The final draft of the coding standard can be found here: http://framework.zend.com/wiki/display/… Look into "Inline Documentation"

@link must not be used within the API doc. Links within the manual are wished. Further external linking should be done with a textual description within the manual.

Also this issue talks about class header and you replied with a function header. This are completly different things.

Matthew, if you're OK with this change can you please assign this to Federico to implement? Personally, I'm OK with a stable link to a descriptive page for the web service, but representing their terms and conditions in ZF is strictly out.

Remove unexist components

What's the status on this issue?

The Simpy package has a link in the docblock for its main class (not the supporting classes) to its API documentation on the service's web site. Think it has since it was originally committed to trunk.