Re: Services_Twitter documentation

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