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:

    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

    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

    
     * 
     * @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?

    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: 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.

    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 (yoshida@zend.co.jp) 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.