Re: Services_Twitter documentation

On Mon, Sep 14, 2009 at 7:31 PM, Michael Gauthier <mike@silverorange.com>wrote: > On Mon, 2009-09-14 at 14:54 +0200, David Jean Louis wrote: > > Hey Christian, > > > > > Hi David, > > > > > > > > >> Documentation is very important indeed, what about setting up a > > >> documentation plan and working on it in the next days ? > > >> I'm not sure it's a good idea to document each twitter API method > > > That's not the scope of peardoc - we have phpdocumentor autogenerated > > > api docs for that. The manual itself shall contain overviews, examples > > > and how-to guides - just as you outlined. > > > > > > > In this particular case, phpdocumentor won't help, we use __call to > > intercept API calls, and since we use $twitter->category->method(), I > > wonder how this should be documented with the @method stuff in > > Services_Twitter class... Chuck or someone else, any idea ? > > > In this case, it's a good idea to document how to make API calls as > David outlined in section 4: > > > This section would explain in details how to make API calls, how to > > deal with required and optional parameters and how to manipulate the > > returned results. > > Here, you should also link to the Twitter API documentation rather than > attempting to reproduce it. By using __call() you're offloading the > responsibility of defining the API to Twitter. It makes sense to offload > the documentation responsibility to Twitter as well. > > Since you're using __call() to wrap another API, I'd say document the > __call() method using a regular API docblock and don't use @method docs. > The @method docs would just duplicate the Twitter API docs, which are > someone else's responsibility to maintain. > > Cheers, > > > Mike > I agree with Mike here... explain everything in the docblock for __call() about how __call() delegates to the Twitter API. You might consider a passing reference in the class docblock to highlight that __call() is doing this, but not much else... I'd probably choose to put all relevant explanations of it in __call()'s docblock. Use a @link tag to link to the Twitter API external docs, in either/both docblocks. -- CRB