[Owncloud] api.owncloud.org

[Thomas Tanghus]

On Saturday 05 October 2013 13:00 Frank Karlitschek wrote:
> Hi guys,
> 
> http://api.owncloud.org is hmmmm, not exactly pretty and easy to understand.
> It's our API reference of our public API for 3rdparty app developers. This
> is created automatically every night from a fresh core checkout with
> phpdoc.
> 
> Can someone here:
> 
> a) Help to make this prettier and easier to understand with a better theme
> or
> b) Can suggest a better tool that we can use?
> 

I'm afraid I can do neither... But I'd like to know/suggest:

* What script does the updating/generating? It doesn't seem to be from 
core/master as many (most) of the interfaces are missing.

* What should be in the API docs? I'd prefer it to be only the stuff in 
lib/public as that is what app devs should care about. Core devs should read 
the in-source docs, which is of course available ;)

* What is the recommended way of documenting? We should really standardize 
this. Now some libs use e.g @brief, some doesn't, which results in the 
generated docs being inconsistent. That should go in the coding guidelines 
docs as well. Also the currently generated docs aren't really intuitive to 
use, as you also mention Frank. I'd prefer a more straight-forward UI, where 
you don't have to click to expand the actual docs.

* Lets mark interfaces/classes/methods with insufficient docs as bugs whenever 
we notice them and assign the issue to either the person mentioned as 
@copyright/@author or whoever git blame shows has the most activity.

-- 
Med venlig hilsen / Best Regards

Thomas Tanghus