Page MenuHomePhabricator
Create Task
Maniphest T7717

docs todo
Open, HighPublic
Actions

Description

Pending documentation improvement tasks:

For all files listed below, somebody with experience in that file should:

  • Add his name after the file (For example @segfaultxavi), so that it is clear who is working on that.
  • Explain the PURPOSE of that class: Why is it needed?
  • Explain how it is USED: First some text (for example: “Instantiate the list widget and add items to it.”) and then some code (only a bit of code with the important parts, not a full program).
  • Indicate special PRECAUTIONS when using this class: These are things that the user of the class has to be careful with.
  • A good example is the Efl.Ui.Box class
  • When the above RAW INFORMATION has been added, the author adds DONE after his name, and then @segfaultxavi will start converting it into a nicely written and formatted text (adding his name after the DONE tag).
NOTE: Some classes are still in @beta stage and might be changed in the future. Work first on non-beta classes.

Empty documentation:

Things like [[]] or [[ ]] are unacceptable.

  • src/lib/elementary/efl_ui_tab_bar.eo @segfaultxavi
  • src/lib/ecore/efl_loop_message_future_handler.eo (@eagleeye )
  • src/lib/ecore/efl_loop_message_future.eo (@eagleeye)
  • src/lib/ecore/ecore_event_message_handler.eo (@eagleeye)

C-style code references

Things like efl_file_set() make no sense for some bindings. They should be replaced with @Efl.File.

Single-line class descriptions:

Half the EO classes have a single-line description. This is OK for parameters or return values but not for classes.

Stable

Beta

  • src/lib/ecore/efl_loop_message_future.eo (@eagleeye)
  • src/lib/ecore/efl_loop_message_future_handler.eo (@eagleeye)
  • src/lib/efl/interfaces/efl_config.eo
  • src/lib/efl/interfaces/efl_control.eo
  • src/lib/efl/interfaces/efl_gfx_buffer.eo
  • src/lib/efl/interfaces/efl_gfx_fill.eo
  • src/lib/efl/interfaces/efl_gfx_frame_controller.eo
  • src/lib/efl/interfaces/efl_gfx_gradient.eo
  • src/lib/efl/interfaces/efl_gfx_gradient_linear.eo
  • src/lib/efl/interfaces/efl_gfx_gradient_radial.eo
  • src/lib/efl/interfaces/efl_gfx_image_load_controller.eo
  • src/lib/efl/interfaces/efl_gfx_path.eo
  • src/lib/efl/interfaces/efl_gfx_shape.eo
  • src/lib/efl/interfaces/efl_gfx_size_class.eo
  • src/lib/efl/interfaces/efl_gfx_text_class.eo
  • src/lib/efl/interfaces/efl_gfx_view.eo
  • src/lib/efl/interfaces/efl_model.eo
  • src/lib/efl/interfaces/efl_observable.eo
  • src/lib/efl/interfaces/efl_observer.eo
  • src/lib/efl/interfaces/efl_playable.eo
  • src/lib/efl/interfaces/efl_player.eo
  • src/lib/efl/interfaces/efl_ui_container_selectable.eo
  • src/lib/efl/interfaces/efl_ui_draggable.eo
  • src/lib/efl/interfaces/efl_ui_i18n.eo
  • src/lib/efl/interfaces/efl_ui_menu.eo
  • src/lib/efl/interfaces/efl_ui_text_selectable.eo
  • src/lib/efl/interfaces/efl_ui_view.eo
  • src/lib/efl/interfaces/efl_ui_view_factory.eo
  • src/lib/efl/interfaces/efl_ui_zoom.eo
  • src/lib/eio/efl_io_manager.eo (@segfaultxavi )
  • src/lib/eio/efl_io_model.eo (@segfaultxavi )
  • src/lib/elementary/efl_access_action.eo
  • src/lib/elementary/efl_access_component.eo
  • src/lib/elementary/efl_access_editable_text.eo
  • src/lib/elementary/efl_access_object.eo
  • src/lib/elementary/efl_access_selection.eo
  • src/lib/elementary/efl_access_text.eo
  • src/lib/elementary/efl_access_value.eo
  • src/lib/elementary/efl_access_widget_action.eo
  • src/lib/elementary/efl_access_window.eo
  • src/lib/elementary/efl_datetime_manager.eo
  • src/lib/elementary/efl_ui_button_legacy_part.eo
  • src/lib/elementary/efl_ui_calendar_item.eo
  • src/lib/elementary/efl_ui_check_legacy_part.eo
  • src/lib/elementary/efl_ui_clock.eo
  • src/lib/elementary/efl_ui_clock_legacy.eo
  • src/lib/elementary/efl_ui_flip.eo
  • src/lib/elementary/efl_ui_flip_part.eo
  • src/lib/elementary/efl_ui_image_factory.eo
  • src/lib/elementary/efl_ui_image_zoomable_pan.eo
  • src/lib/elementary/efl_ui_layout_factory.eo
  • src/lib/elementary/efl_ui_layout_part_bg.eo
  • src/lib/elementary/efl_ui_layout_part_content.eo
  • src/lib/elementary/efl_ui_layout_part.eo
  • src/lib/elementary/efl_ui_list_view_pan.eo
  • src/lib/elementary/efl_ui_navigation_bar_part_back_button.eo
  • src/lib/elementary/efl_ui_navigation_bar_part.eo
  • src/lib/elementary/efl_ui_panes_part.eo
  • src/lib/elementary/efl_ui_progressbar_legacy_part.eo
  • src/lib/elementary/efl_ui_progressbar_part.eo
  • src/lib/elementary/efl_ui_radio_legacy_part.eo
  • src/lib/elementary/efl_ui_selection.eo
  • src/lib/elementary/efl_ui_state_model.eo
  • src/lib/elementary/efl_ui_tab_bar.eo @segfaultxavi
  • src/lib/elementary/efl_ui_tab_bar_default_item.eo @segfaultxavi
  • src/lib/elementary/efl_ui_tab_page.eo @segfaultxavi
  • src/lib/elementary/efl_ui_tab_pager.eo @segfaultxavi
  • src/lib/elementary/efl_ui_text_editable.eo
  • src/lib/elementary/efl_ui_text_part.eo
  • src/lib/elementary/efl_ui_textpath.eo
  • src/lib/elementary/efl_ui_textpath_part.eo
  • src/lib/elementary/efl_ui_theme.eo
  • src/lib/elementary/efl_ui_video.eo
  • src/lib/elementary/efl_ui_win_part.eo
  • src/lib/elementary/efl_ui_animation_view.eo (Needs proofreading)
  • src/lib/emotion/efl_canvas_video.eo
  • src/lib/evas/canvas/efl_canvas_animation_player.eo
  • src/lib/evas/canvas/efl_canvas_filter_internal.eo
  • src/lib/evas/canvas/efl_canvas_polygon.eo
  • src/lib/evas/canvas/efl_canvas_rectangle.eo
  • src/lib/evas/canvas/efl_canvas_scene3d.eo
  • src/lib/evas/canvas/efl_canvas_surface_tbm.eo
  • src/lib/evas/canvas/efl_canvas_surface_wayland.eo
  • src/lib/evas/canvas/efl_canvas_surface_x11.eo
  • src/lib/evas/canvas/efl_canvas_vg_container.eo
  • src/lib/evas/canvas/efl_canvas_vg_gradient.eo
  • src/lib/evas/canvas/efl_canvas_vg_gradient_linear.eo
  • src/lib/evas/canvas/efl_canvas_vg_gradient_radial.eo
  • src/lib/evas/canvas/efl_canvas_vg_image.eo
  • src/lib/evas/canvas/efl_canvas_vg_node.eo
  • src/lib/evas/canvas/efl_canvas_vg_shape.eo
  • src/lib/evas/canvas/efl_canvas_text.eo (Broken English)
  • src/lib/evas/canvas/efl_input_clickable.eo
  • src/lib/evas/canvas/efl_text_cursor.eo (Comments from D10542)

Need more detail:

  • src/lib/ecore/efl_loop_message_future_handler.eo (@eagleeye)
  • src/lib/elementary/efl_ui_*_factory.eo (@felipealmeida)

Formatting problems:

Other tasks:

  • T7702 Remove internally generated classes from EFL# doc
  • References to EO types (Like Efl.Ui.Widget) without using @.

Already done:

Legacy:

  • src/lib/ecore_audio/ecore_audio.eo
  • src/lib/ecore_audio/ecore_audio_in.eo
  • src/lib/ecore_audio/ecore_audio_in_sndfile.eo
  • src/lib/ecore_audio/ecore_audio_in_tone.eo
  • src/lib/ecore_audio/ecore_audio_out.eo
  • src/lib/ecore_audio/ecore_audio_out_pulse.eo
  • src/lib/ecore_audio/ecore_audio_out_sndfile.eo
  • src/lib/ecore_audio/ecore_audio_out_wasapi.eo
  • src/lib/ecore/ecore_event_message.eo
  • src/lib/ector/cairo/ector_renderer_cairo.eo
  • src/lib/ector/cairo/ector_renderer_cairo_gradient_linear.eo
  • src/lib/ector/cairo/ector_renderer_cairo_gradient_radial.eo
  • src/lib/ector/cairo/ector_renderer_cairo_shape.eo
  • src/lib/ector/ector_renderer.eo
  • src/lib/ector/ector_renderer_gradient.eo
  • src/lib/ector/ector_renderer_gradient_linear.eo
  • src/lib/ector/ector_renderer_gradient_radial.eo
  • src/lib/ector/ector_renderer_image.eo
  • src/lib/ector/ector_renderer_shape.eo
  • src/lib/ector/ector_surface.eo
  • src/lib/ector/gl/ector_gl_buffer.eo
  • src/lib/ector/gl/ector_gl_surface.eo
  • src/lib/ector/gl/ector_renderer_gl.eo
  • src/lib/ector/gl/ector_renderer_gl_gradient_linear.eo
  • src/lib/ector/gl/ector_renderer_gl_gradient_radial.eo
  • src/lib/ector/gl/ector_renderer_gl_shape.eo
  • src/lib/ector/software/ector_renderer_software.eo
  • src/lib/ector/software/ector_renderer_software_gradient_linear.eo
  • src/lib/ector/software/ector_renderer_software_gradient_radial.eo
  • src/lib/ector/software/ector_renderer_software_image.eo
  • src/lib/ector/software/ector_renderer_software_shape.eo
  • src/lib/ector/software/ector_software_buffer_base.eo
  • src/lib/ector/software/ector_software_buffer.eo
  • src/lib/ector/software/ector_software_surface.eo
  • src/lib/eio/eio_sentry.eo
  • src/lib/eldbus/eldbus_model_arguments.eo (@segfaultxavi)
  • src/lib/eldbus/eldbus_model_connection.eo (@segfaultxavi)
  • src/lib/eldbus/eldbus_model_method.eo (@segfaultxavi)
  • src/lib/eldbus/eldbus_model_object.eo (@segfaultxavi)
  • src/lib/eldbus/eldbus_model_proxy.eo (@segfaultxavi)
  • src/lib/eldbus/eldbus_model_signal.eo (@segfaultxavi)
  • src/lib/elementary/elm_actionslider_part.eo
  • src/lib/elementary/elm_bubble_part.eo
  • src/lib/elementary/elm_code_widget.eo
  • src/lib/elementary/elm_ctxpopup_part.eo
  • src/lib/elementary/elm_dayselector_part.eo
  • src/lib/elementary/elm_entry_part.eo
  • src/lib/elementary/elm_fileselector_entry_part.eo
  • src/lib/elementary/elm_fileselector_part.eo
  • src/lib/elementary/elm_flip_part.eo
  • src/lib/elementary/elm_hover_part.eo
  • src/lib/elementary/elm_interface_scrollable.eo
  • src/lib/elementary/elm_label_part.eo
  • src/lib/elementary/elm_mapbuf_part.eo
  • src/lib/elementary/elm_multibuttonentry_part.eo
  • src/lib/elementary/elm_naviframe_part.eo
  • src/lib/elementary/elm_panel_part.eo
  • src/lib/elementary/elm_player_part.eo
  • src/lib/elementary/elm_popup_part.eo
  • src/lib/elementary/elm_scroller_part.eo
  • src/lib/evas/canvas/evas_canvas3d_camera.eo
  • src/lib/evas/canvas/evas_canvas3d_light.eo
  • src/lib/evas/canvas/evas_canvas3d_material.eo
  • src/lib/evas/canvas/evas_canvas3d_mesh.eo
  • src/lib/evas/canvas/evas_canvas3d_node.eo
  • src/lib/evas/canvas/evas_canvas3d_object.eo
  • src/lib/evas/canvas/evas_canvas3d_primitive.eo
  • src/lib/evas/canvas/evas_canvas3d_scene.eo
  • src/lib/evas/canvas/evas_canvas3d_texture.eo

Details

Differential Revisions
D8496: docs: Fill-in parts docs for Efl.Ui.Grid_Default_Item
Commits
D9884 / rEFLcbbc1ff675a4: efl_ui/popup: improve backwall docs
D9876 / rEFL8f3c543e71d1: docs: fix invalid $class reference to use @class
D9929 / rEFL16a93a537459: efl/image: improve docs
D9912 / rEFL7d727bbb2621: efl/arrangement: improve docs
D9883 / rEFL6d49eb7cc272: efl_ui/alert_popup: improve docs
D9882 / rEFL08e5b09d0a98: efl_ui/popup: improve docs
D9885 / rEFL42abe377b56b: efl_ui/flox_box: improve docs
D9884 / rEFL0867b51a1ddf: efl_ui/popup: improve backwall docs
D9881 / rEFLc10c9b21cc43: efl_ui/scrollable_content: improve docs
D9876 / rEFL1148ab339308: docs: fix invalid $class reference to use @class
D9783 / rEFL784de4d4711d: efl_ui_*_default_item: improve docs
D8495 / rEFL413c987837f0: docs: Update refs to Efl.Ui.Theme.Apply_Error
D8498 / rEFL6c01d7177cc0: docs: Format efl_file.h
rEFL57da0bee3d3c: docs: Fix common misspellings in EO files
rEFL68c530080b7d: docs: Fix common misspellings in H files
D8494 / rEFL291ab9a671bf: docs: Efl.Ui.Layout_Base update theme docs
D8511 / rEFL01fccf6a8731: docs: Clarify Efl.Ui.Win exit_on_close methods

Related Objects
Search...

StatusAssignedTask
 OpenNoneT5826 Improve overall EFL documentation
 OpenmyoungwoonT7717 docs todo
There are a very large number of changes, so older changes are hidden. Show Older Changes
bu5hm4n added a comment.Aug 26 2019, 10:47 PM

Just be careful with efl_ui_tab_bar, there is a major cleanup pending in review, which removes most of the API.

segfaultxavi updated the task description. (Show Details)Aug 27 2019, 7:56 AM
myoungwoon updated the task description. (Show Details)Aug 28 2019, 1:05 AM
myoungwoon added subscribers: Hermet, woohyun.Aug 28 2019, 1:12 AM

I revmoved ector related eo files because ectors are neither using the actual header files nor installed.
and I assigned you to eldbus because eldbus and dbus had not been using owing to security issue and there are no one to have knowledge and experience about dbus.
So I think that it is enough for @segfaultxavi to add brief description to each APIs.
Mainly, elementary related to eo files will be handled by @woohyun and evas related to eo files will be covered by @Hermet and rest will be handled by @myoungwoon.

segfaultxavi added a comment.Aug 28 2019, 1:21 AM

OK, I'll move the unwanted files to another section but remove the "done" mark, so they are not forgotten.

segfaultxavi updated the task description. (Show Details)Aug 28 2019, 1:26 AM
segfaultxavi updated the task description. (Show Details)Aug 28 2019, 4:12 AM

I've moved all Legacy classes to a separate section, since I guess we want to prioritize Unified classes.

myoungwoon updated the task description. (Show Details)Aug 28 2019, 11:29 PM
myoungwoon added subscribers: akanad, • wc, eagleeye.
segfaultxavi updated the task description. (Show Details)Aug 29 2019, 5:18 AM
myoungwoon updated the task description. (Show Details)Aug 29 2019, 11:52 PM

I submitted my patches for my part. Please review D9795.
https://phab.enlightenment.org/D9795
Thanks.

segfaultxavi updated the task description. (Show Details)Aug 30 2019, 3:04 AM
segfaultxavi updated the task description. (Show Details)Sep 2 2019, 1:46 AM
segfaultxavi updated the task description. (Show Details)Sep 2 2019, 2:59 AM
segfaultxavi updated the task description. (Show Details)Sep 2 2019, 7:31 AM
segfaultxavi updated the task description. (Show Details)Sep 3 2019, 2:47 AM
segfaultxavi updated the task description. (Show Details)Sep 3 2019, 8:58 AM
segfaultxavi updated the task description. (Show Details)Sep 3 2019, 10:27 AM
zmike updated the task description. (Show Details)Sep 9 2019, 8:03 AM
zmike updated the task description. (Show Details)Sep 9 2019, 11:21 AM
segfaultxavi updated the task description. (Show Details)Sep 10 2019, 2:54 AM
segfaultxavi updated the task description. (Show Details)Sep 10 2019, 4:02 AM
segfaultxavi updated the task description. (Show Details)Sep 10 2019, 7:02 AM
segfaultxavi updated the task description. (Show Details)Sep 10 2019, 8:15 AM
zmike updated the task description. (Show Details)Sep 11 2019, 11:02 AM
segfaultxavi updated the task description. (Show Details)Sep 12 2019, 2:30 AM
segfaultxavi updated the task description. (Show Details)Sep 12 2019, 3:04 AM
segfaultxavi updated the task description. (Show Details)Sep 12 2019, 3:08 AM
bu5hm4n updated the task description. (Show Details)Sep 13 2019, 3:33 AM
zmike updated the task description. (Show Details)Sep 13 2019, 8:31 AM
zmike updated the task description. (Show Details)Sep 13 2019, 8:39 AM
zmike updated the task description. (Show Details)Sep 13 2019, 8:42 AM
zmike updated the task description. (Show Details)
segfaultxavi updated the task description. (Show Details)Sep 13 2019, 9:30 AM
zmike added a comment.Sep 13 2019, 10:46 AM

We need to also ensure that default values are documented for all properties. I think this would require a lua script which:

  • scans provided eo files
  • prints out all properties+values in a format that's easy to parse in shell scripts
  • grep the output for 'default value' on each value

This is extremely important for interfaces, as it ensures that all objects which implement the interface will conform to the specification in the eo file.

zmike added a comment.Sep 13 2019, 11:06 AM

Also need to evaluate all events for using past tense verbs (e.g., we should ensure we use resized and not resize)

zmike updated the task description. (Show Details)Sep 13 2019, 11:20 AM
CHAN added a subscriber: CHAN.Sep 17 2019, 9:42 PM

D10000 I made a commit for my parts (Efl.Threadio, Efl.Appthread)

myoungwoon updated the task description. (Show Details)Sep 18 2019, 1:31 AM

I submitted my patches for my part. Please review D10002.
https://phab.enlightenment.org/D10002
Thanks.

segfaultxavi updated the task description. (Show Details)Sep 19 2019, 2:26 AM
segfaultxavi updated the task description. (Show Details)Sep 19 2019, 4:04 AM
segfaultxavi updated the task description. (Show Details)
segfaultxavi updated the task description. (Show Details)Sep 19 2019, 4:13 AM
segfaultxavi updated the task description. (Show Details)Sep 19 2019, 9:38 AM
akanad added a comment.Sep 23 2019, 6:47 PM

src/lib/ecore/efl_exe.eo (@akanad) seems done with your(@segfaultxavi) comit (f78b4861af140bd5b333fb530556e81915acbaab).

segfaultxavi updated the task description. (Show Details)Sep 24 2019, 8:26 AM
segfaultxavi updated the task description. (Show Details)Sep 30 2019, 2:50 AM
segfaultxavi updated the task description. (Show Details)Oct 2 2019, 6:17 AM
segfaultxavi updated the task description. (Show Details)Oct 31 2019, 9:03 AM
segfaultxavi updated the task description. (Show Details)Nov 5 2019, 2:31 AM
akanad added a comment.Nov 5 2019, 11:50 PM

@segfaultxavi
I tried to improve descriptions for efl_loop_message_future.eo and efl_loop_message_future_handler.eo.
They look like actually unused, though.
I mean they are created and assigned but there isn't a place that accesses or call some apis to those things.
Am I wrong?

segfaultxavi added a comment.Nov 6 2019, 6:10 AM

It could be that these classes are currently unused, yes. @cedric should know. @cedric?

segfaultxavi updated the task description. (Show Details)Nov 6 2019, 6:52 AM
segfaultxavi updated the task description. (Show Details)Nov 6 2019, 7:12 AM
segfaultxavi updated the task description. (Show Details)Nov 19 2019, 7:41 AM
segfaultxavi updated the task description. (Show Details)Nov 19 2019, 7:46 AM
segfaultxavi updated the task description. (Show Details)Nov 19 2019, 7:52 AM
segfaultxavi updated the task description. (Show Details)Nov 20 2019, 3:28 AM
segfaultxavi updated the task description. (Show Details)Dec 18 2019, 3:54 AM