Page MenuHomePhabricator

edocgen: Remaining issues
Open, HighPublic

Description

These are the remaining issues detected with the current version of edocgen.
The output can be found at the playground.
Links in the playground will take you to the online docs under /develop/, so here are a few direct playground links for your convenience:
A class: https://www.enlightenment.org/playground/api/efl/ui/box
A method: https://www.enlightenment.org/playground/api/efl/ui/box/method/pack_after
A property: https://www.enlightenment.org/playground/api/efl/ui/box/property/homogeneous
The above docs have been generated with D10318 applied, which is still being discussed.

Remaining issues:

  • Allow generating documentation only for stable (non-beta) classes. Beta classes should be removed from the listings, and any reference to them should be rendered with grayed-out text (instead of a link) followed by this text: (object still in beta stage).
  • Classes should only list their own members in the Members section, all inherited members should be listed in the Inherited section. Documentation in the implements section in EO files (seldom used) can be appended to the summary in the Inherited section.
  • Method, Property, Event, Alias, Struct... pages are lacking a title header. D10318 handles Properties and Methods but the others are still missing.
  • Right now there is this short version of "Inheritance" that starts with the parent class. I think it would be nice to have there as well the list of interfaces and mixins that are directly inherited, just with a link so you can click on it.
  • Make the inherited sections collapsable
  • The Members are kind of very "short" if this list gets shorter due to bullet point 2, we could make something that is a little bit more "verbose" telling what the members are etc.
  • The Titles in the property view could get links to jump back to the widget they are on.
  • The idea from k-s http://i.imgur.com/EINws0S.png to have something like "C usage" also looks very very nice, maybe something to consider ? -- @q66: this was already done before
segfaultxavi triaged this task as High priority.
segfaultxavi updated the task description. (Show Details)Oct 10 2019, 4:26 AM
bu5hm4n added subscribers: cedric, bu5hm4n.EditedJan 14 2020, 4:19 AM

Just from the top of my head:

  • Right now there is this short version of "Inheritance" that starts with the parent class. I think it would be nice to have there as well the list of interfaces and mixins that are directly inherited, just with a link so you can click on it.
  • Maybe we can join the Inherited section with the event section, it feels akward to me to have them doubled.
  • The Members are kind of very "short" if this list gets shorter due to bullet point 2, we could make something that is a little bit more "verbose" telling what the members are etc.
  • The Titles in the property view could get links to jump back to the widget they are on.
  • The idea from k-s http://i.imgur.com/EINws0S.png to have something like "C usage" also looks very very nice, maybe something to consider ?
  • I get the navigation bar on every site, is it possibleto turn it off, its a little bit out of place here.
  • And a bug, taking https://www.enlightenment.org/develop/api/efl/ui/collection and clicking on Efl.Ui.Multi_Selectable.select_mode will not redirect you to a valid page.

@stefan_schmidt @q66 @segfaultxavi @cedric Any other ideas ?

bu5hm4n updated the task description. (Show Details)Jan 14 2020, 8:40 AM
q66 updated the task description. (Show Details)Jan 22 2020, 8:54 AM
q66 updated the task description. (Show Details)Jan 30 2020, 7:55 AM

Regarding how to render inheritance, let's recap:

  • A class can offer 3 different kinds of methods:
    1. Its own methods
    2. Overridden / Implemented methods (the class provides its own implementation for a method defined somewhere else)
    3. Inherited methods (Accessible through the class, but the implementation is somewhere else)
  • I don't think the user of the docs is interested in this distinction at all. He just wants to know what methods are available in this class.
  • However, listing ALL methods together is way too messy. Typically the user is not interested in inherited members.

Therefore, I would do something similar as they do here, for example:
https://developer.android.com/reference/android/view/ViewGroupOverlay#public-methods

  • A Public methods section containing kinds 1 and 2, merged.
    • Docs for kind 2 would include all docs from parent classes, one after the other, from more generic to more specific. Even though a class is free to reimplement a method any way it wants, the docs from the interface should still apply, otherwise, that should be a new method and not an implementation... no?
    • Methods of kind 2 can contain a small link to the base class or interface (Overridden from...) but it won't be very useful since the documentation has already been copied into this class.
  • An Inherited methods section containing kind number 3.
    • This section should be collapsible and be collapsed by default.
    • It can contain the whole docs or only summary and link to docs page.

Are you sure you are not meaning with the second kind the overrides and implements that have a special documentation ?

Noone is interested in the fact that the constructor is overwritten, this stuff should not be part of the "Public methods" section.

That is true, if a method doesn't have its own docs (like most constructor), it's not worth putting them at the forefront of the documentation.
This will remove a lot of unnecessary text from the current docs.
For example, Efl.Ui.Button (here) will have an empty Public methods section.

q66 updated the task description. (Show Details)Feb 6 2020, 6:02 AM
q66 updated the task description. (Show Details)Feb 13 2020, 5:55 AM