switch API from ApiGen to Sami?

Permalink 1 user found helpful
The current API onhttp://documentation.concrete5.org/api/... is created using ApiGen. After using API created using Sami, I think switching to it would save time and add a lot of useful features.

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.


Laravel API

Symfony API

1 Attachment

View Replies:
Mainio replied on at Permalink Reply
I see the usability advantages in the tool switching, especially the direct linking to GitHub code and quick switching between versions. But, it does not make the actual API docs much more appealing to me. For me at least, these usability improvements would not make me use these docs much more. I almost never use these docs when working with concrete5.

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.
MrKDilkington replied on at Permalink Reply

I wanted to follow up on this and say that commenting the core and adding examples would be a fantastic idea.

One step would be commenting/adding examples to new core code added from now on.

The bigger question, how do we comment the current core code. I would be interested in ideas of how to use the community to get this done.
JohntheFish replied on at Permalink Reply
Comments in code desperately need to add value and explanation rather than just repeat the interface in a format that api generators and IDE editors use.

A couple of old threads.



Unfortunately, while the current v8 core has a growth of @doc comments for the api and doctrine, it appears to have an even lower density of added value anecdotal comments than the core of 5 years ago. So we have a more complex architecture (even if it is more systematic) with less information on how it fits together. There will never be written documentation good enough to remove the need for developers to do code archaeology, so inline comments need to be written with the that in mind.