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

Issue Type: Improvement Created: 2008-05-08T12:04:06.000+0000 Last Updated: 2009-11-13T03:24:53.000+0000 Status: Closed Fix version(s): Reporter: fc (federico.cargnelutti) Assignee: Matthew Weier O'Phinney (matthew) Tags: - Zend_Service_Akismet

  • Zend_Service_Amazon
  • Zend_Service_Audioscrobbler
  • Zend_Service_Delicious
  • Zend_Service_Flickr
  • Zend_Service_Nirvanix
  • Zend_Service_Simpy
  • Zend_Service_SlideShare
  • Zend_Service_StrikeIron
  • Zend_Service_Technorati
  • Zend_Service_Yahoo

Related issues: Attachments: - StLouisNingNetworkDevelopers[1]


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.


Posted by Thomas Weidner (thomas) on 2008-05-10T03:06:37.000+0000

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.

Posted by Simone Carletti (weppos) on 2008-05-13T15:25:34.000+0000

{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

<pre class="highlight">
     * @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    <a href=""></a> 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?

Posted by Simone Carletti (weppos) on 2008-05-13T15:27:49.000+0000

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

Posted by Thomas Weidner (thomas) on 2008-05-14T13:21:53.000+0000

The final draft of the coding standard can be found here:… 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.

Posted by Wil Sinclair (wil) on 2008-06-09T12:05:40.000+0000

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.

Posted by old of Satoru Yoshida ( on 2008-12-26T05:13:11.000+0000

Remove unexist components

Posted by Dolf Schimmel (Freeaqingme) (freak) on 2009-08-11T08:15:32.000+0000

What's the status on this issue?

Posted by Matthew Turland (elazar) on 2009-08-11T10:17:03.000+0000

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.

Have you found an issue?

See the Overview section for more details.


© 2006-2018 by Zend, a Rogue Wave Company. Made with by awesome contributors.

This website is built using zend-expressive and it runs on PHP 7.