Re: [E-devel] Unified API docs

[Andrew W. <an...@an...>]

Hi,

Thanks for the feedback, much sounds like what I had hoped to add (this was
a first pass to trim out the bulk - more layout and styling to be done).

On your first point the question is whether this is abstract documentation
or language specific. The view that I have taken in formatting these docs
is that the declared members within a class should provide specifics but
all inherited items (and in some cases there are hundreds) we should not be
so verbose. The reason for this is that the current class is a unit in
itself, If I am browsing the API for a button then I am likely not so
interested in layouts or focus management. One reason that this does not
currently look quite right is that overridden members are omitted in the
class documentation - I need to fix that for this to work as planned (i.e.
where "overridden here" there will be a full spec listed higher in the doc).

The sorting has not been altered in this change, I agree that could be
worked on and I intend to look at that shortly. Grouping was next on my
list. The suggestion of a table is a good one, I will see how that looks.

I'll post here when there is more to review,
Thanks,
Andy

On Tue, 12 Dec 2017 at 02:12 Carsten Haitzler <ra...@ra...> wrote:

> On Mon, 11 Dec 2017 17:37:10 +0000 Andrew Williams <an...@an...>
> said:
>
> Looks good, but I think it's too trimmed. Maybe it's just that in every
> language I know a method, function, etc. also lists its inputs and outputs
> (return and argument names/types). and not having that there even in
> shorthand
> makes it harder to know at a glance if that is what I want.
>
>   Efl.Text.Markup.markup (get, set)
>   Efl.Text.text (get, set) [Overridden here]
>
> for example. what does it take? a string? i guess so... but i'm not sure. 1
> parameter or 2 what about:
>
>   Efl.Ui.Layout.theme (set)
>
> what does this take to set? i happen to know it's a string... but knowing
> at a
> glance what these are would make these far more useful.
>
> Also I notice sorting is odd. The protected methods are sorted separately
> to the
> rest. Wouldn't it make sense to at least separate off a "protected" section
> then instead of adding protected to each entry?
>
> Just for "aesthetics" wouldn't it be also nicer to put the list of
> methods/properties in a table?  If we're sorting by parent class
> (Efl.Ui.Cursor, Efl.Ui.Layout etc. etc.) why repeat this per line? start a
> table row with the class name then list all the properties/methods over the
> next N lines (perhaps indented) like:
>
>   | Efl.Text.Markup
> |
>   |  | cursor_markup_insert       | method    |
> |
>   |  | markup                     | get | set |
> |
>   | Efl.Text
>  |
>   |  | text                       | get | set | [Overridden here]
> |
>   | Efl.Ui.Autorepeat
> |
>   |  | autorepeat_enabled         | get | set | [Overridden here]
> |
>   |  | autorepeat_gap_timeout     | get | set | [Overridden here]
> |
>   |  | autorepeat_initial_timeout | get | set | [Overridden here]
> |
>   |  | autorepeat_supported       | get |     | [Overridden here]
> |
>   | Efl.Ui.Base
> |
>   |  | language                   | get | set |
> |
>   |  | mirrored_automatic         | get | set | [Overridden in Elm.Widget]
> |
>   |  | mirrored                   | get | set | [Overridden in Elm.Widget]
> |
>
> without the actual table border lines - keep it blank with padding to
> space it
> out, perhaps the "Efl.Ui.Base" class inheritance headers having a different
> background color for the table row to delineate sections more easily.
> removal
> of the parent class to a header should create a bit more room for the
> arguments
> and returns i mentioned above...
>
> similarly for events? just suggestions.
>
> > Hi,
> >
> > I have done some significant updates to the new API docs. The layout
> still
> > wants a little tweaking but they should be more readable than they were
> > before. I've trimmed the fat out of all inherited members as discussed
> > before.
> >
> > The result is that a page like
> > www.enlightenment.org/develop/api/efl/ui/button which has no members of
> > it's own has gone down from 300k to 128k (according to curl).
> >
> > This should help our average page load time a lot - and it needs work as
> we
> > are sitting at 4sec currently!
> >
> > Let me know if you see any problems with the new trimmed rendering.
> >
> > Thanks,
> > Andy
> > --
> > http://andywilliams.me
> > http://ajwillia.ms
> >
> ------------------------------------------------------------------------------
> > Check out the vibrant tech community on one of the world's most
> > engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> > _______________________________________________
> > enlightenment-devel mailing list
> > enl...@li...
> > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
> >
>
>
> --
> ------------- Codito, ergo sum - "I code, therefore I am" --------------
> Carsten Haitzler - ra...@ra...
>
> --
http://andywilliams.me
http://ajwillia.ms