API documentation navigation / style / source code linking issues

[pxwee5]

One thing I like about SilverStripe was the (old) api documentation, where the text are properly sized and there's a link to the source code.

The new api documentation is a step backwards - http://api.silverstripe.org/3/DataObject.html
It's nearly impossible to manoeuvre:

1. Awkward heading sizes
2. Page is too long in my opinion
3. v3 points to which version? v3.1? or v3.6?
4. No link to source code
5. No text color
6. Method summary & method elaboration shows no major differences (might as well link me to the source code like the old doc)
7. Don't know what at line 3756 is supposed to tell. Might as well use this as a link to the source code like before.
8. Too much repeating information in one page.

Consider reverting it and if re-styling is really necessary, do it properly.

If you're stuck with the new API documentation generator, consider re-styling it so that the UI looks like the old api doc.

[tractorcow]

It's been raised that we might need a "hide inherited members" feature, maybe on by default, so that you can limit the page to only members at the current inheritance. That should address 2.

Also having non-massive classes is probably the real "fix" for this issue; We shouldn't have 4000 line classes.

@clarkepaul can you provide design advice on 1. and 5. and see if there are some style improvements we can make?

When we add back links to source code, that will cover 4. / 7.

Regarding 3., we no longer maintain separate API docs for specific minor versions. We may re-introduce this at some future time, for our expectation is that users should be able to upgrade minor versions on projects under active development without breakages.

On 6. the major difference is the documentation on method arguments becomes visible.

Maybe regarding 6. / 8. we could restructure the summary / elaboration... clicking the summary "expands" the elaboration directly below, similar to an accordion. @clarkepaul what do you think about this?

E.g.

Expands into

We could have an "expand all" button somewhere, similar to the "show inherited members" action.

[tractorcow]

Related silverstripe/api.silverstripe.org#56

[clarkepaul]

Add to design backlog, no timeframes yet as to when we can look into it.

[andrewandante]

@pxwee5 in answer to your other question, reversion is not possible due to silverstripe/api.silverstripe.org#45 - hence the rush to get the new documentation available in any form at all.

@clarkepaul would be good to know when it can be prioritised - there has been a lot of "constructive criticism" from the community on this one 😃

[chillu]

While most of this feedback sounds reasonable, I'd like to point out that SAMI is used by possibly the largest PHP library around: http://api.symfony.com/.

I've broken up this ticket in to relevant bits where appropriate:

1. Awkward heading sizes
2. No text color
   Styling on new API: Heading sizes, text colour api.silverstripe.org#61

4. No link to source code
   Link to Github source code api.silverstripe.org#59

2. Page is too long
   Hide inherited members by default api.silverstripe.org#60

6. Method summary
7. Too much repeated info
   Too much repeating info  api.silverstripe.org#62

On the notion of "doing it properly", just a friendly reminder that everything about this effort is open source, including this repository - you don't even need to know any SilverStripe to get cracking ;)

Closing this ticket, since it has multiple issues which I hope are captured elsewhere now - with their own impact ratings, and separate priorities for the backlog.