switch API from ApiGen to Sami?1 user found helpful
The features that immediately stand out:
- methods are part of search results (including auto-complete)
- you can jump from Classes, Namespaces, Interfaces, and Traits
- there is an index
The Symfony API search auto-completes in a resizable iframe which makes searching faster and easier to see longer namespaces. Please see attached screenshot.
It looks like you can configure whether you want to jump to code or not. Symfony just lists lines and Laravel jumps to code on GitHub. I imagine we would want to jump to code hostedhttp://documentation.concrete5.org/api....
If the core team doesn't have the time to implement this. Is anyone else interested in hosting this?
Sami is open-source Sensio code.
The biggest thing missing from the API docs currently for c5 are code comments (for the most parts) and the amount of available examples within these comments. This has always been the pain part with c5 and still seems to be. But there has been some good progress going on regarding this after the 5.7 development branch was opened for external users, so I haven't lost hope on this (+ the latest improvements on the docs site are very good progress as well).
The best API docs that I personally really enjoy reading are with Rails. Take a look at their approach on giving the examples (+ you can either directly take a look at the source on the page or click the GitHub link if you want to dig deeper, makes it much quicker to use):
Of course, they have "a couple" more developers who spend time commenting the code base but just saying, this is what it **should** be in the perfect world.
I also prefer their structure of the page compared to most of the PHP apidoc creators because usually when you're reading these, you're only interested in the one class or the one method you're looking for. No need to show the whole class tree or anything like that in my opinion.
I almost always use these docs when I'm working with Rails.