Page MenuHomePhabricator

docs todo
Open, HighPublic

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_layout_factory.eo (@felipealmeida)
  • src/lib/elementary/efl_ui_tab_bar.eo (@bowonryu)
  • src/lib/ecore/efl_threadio.eo (@wc )
  • src/lib/ecore/efl_loop_message_future_handler.eo (@eagleeye )
  • src/lib/ecore/efl_appthread.eo (@wc)
  • 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.

  • src/lib/eo/efl_object.eo
  • src/lib/elementary/efl_ui_image.eo
  • src/lib/efl/interfaces/efl_part.eo
  • src/lib/efl/interfaces/efl_model.eo
  • src/lib/efl/interfaces/efl_gfx_path.eo
  • src/lib/efl/interfaces/efl_ui_scrollable_interactive.eo

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

  • src/lib/efl/interfaces/efl_gfx_image_orientable.eo
  • src/lib/evas/canvas/efl_input_hold.eo

Beta

  • src/lib/ecore/efl_appthread.eo (@wc)
  • src/lib/ecore/efl_bounce_interpolator.eo (@Hermet )
  • src/lib/ecore/efl_cubic_bezier_interpolator.eo (@Hermet )
  • src/lib/ecore/efl_divisor_interpolator.eo (@Hermet )
  • src/lib/ecore/efl_filter_model.eo (@akanad)
  • src/lib/ecore/efl_linear_interpolator.eo (@Hermet )
  • src/lib/ecore/efl_loop_message_future.eo (@eagleeye)
  • src/lib/ecore/efl_loop_message_future_handler.eo (@eagleeye)
  • src/lib/ecore/efl_spring_interpolator.eo (@Hermet )
  • src/lib/ecore/efl_threadio.eo (@wc)
  • src/lib/efl/interfaces/efl_cached_item.eo
  • 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_color_class.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.eo (@zmike)
  • 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_interpolator.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_factory.eo
  • src/lib/efl/interfaces/efl_ui_i18n.eo
  • src/lib/efl/interfaces/efl_ui_menu.eo
  • src/lib/efl/interfaces/efl_ui_scrollable.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
  • src/lib/elementary/efl_ui_table_static.eo
  • src/lib/elementary/efl_ui_tab_page.eo
  • src/lib/elementary/efl_ui_tab_pager.eo
  • 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_widget_part_bg.eo
  • src/lib/elementary/efl_ui_win_part.eo
  • src/lib/emotion/efl_canvas_video.eo
  • src/lib/evas/canvas/efl_canvas_animation_alpha.eo
  • src/lib/evas/canvas/efl_canvas_animation.eo
  • src/lib/evas/canvas/efl_canvas_animation_group.eo
  • src/lib/evas/canvas/efl_canvas_animation_group_parallel.eo
  • src/lib/evas/canvas/efl_canvas_animation_group_sequential.eo
  • src/lib/evas/canvas/efl_canvas_animation_player.eo
  • src/lib/evas/canvas/efl_canvas_animation_rotate.eo
  • src/lib/evas/canvas/efl_canvas_animation_scale.eo
  • src/lib/evas/canvas/efl_canvas_animation_translate.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_input_clickable.eo
  • src/lib/evas/gesture/efl_canvas_gesture_double_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_flick.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_long_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_manager.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_momentum.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_recognizer_double_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_recognizer_flick.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_recognizer_long_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_recognizer_momentum.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_recognizer_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_recognizer_triple_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_recognizer_zoom.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_touch.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_triple_tap.eo (@myoungwoon) DONE
  • src/lib/evas/gesture/efl_canvas_gesture_zoom.eo (@myoungwoon) DONE

Need more detail:

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

Formatting problems:

  • Use of $: Eolian only highlights letters and underscores. $one_two looks right, but $one.two looks wrong. Remove the $ in all the wrong cases.

Other tasks:

  • T7702 Remove internally generated classes from EFL# doc

Already done:

  • check out efl.ui.layout theme docs
  • verify doc refs for efl.gfx.image.load_error in load_error get methods
  • verify doc refs for efl.ui.theme.apply_error in efl_ui_layout_base and efl_ui_widget
  • src/lib/elementary/efl_ui_grid_default_item.eo @bu5hm4n DONE @segfaultxavi
  • efl_file.h
  • efl_ui_win.eo: clearly separate exit_on_close and exit_on_windows_close (this is a class method).
  • Anything containing common misspellings like setted, splitted, etc...
  • src/lib/efl/interfaces/efl_ui_range_display.eo @segfaultxavi
  • src/lib/elementary/efl_ui_popup_part_backwall.eo (@zmike)
  • src/lib/elementary/efl_ui_focus_parent_provider.eo @segfaultxavi
  • src/lib/elementary/efl_ui_box_flow.eo (@zmike) DONE @segfaultxavi
  • src/lib/elementary/efl_ui_focus_composition_adapter.eo @segfaultxavi
  • src/lib/elementary/efl_ui_list.eo @bu5hm4n DONE @segfaultxavi
  • src/lib/elementary/efl_ui_alert_popup_part.eo (@zmike)
  • src/lib/elementary/efl_ui_focus_util.eo @segfaultxavi
  • src/lib/elementary/efl_ui_collection_focus_manager.eo @segfaultxavi
  • src/lib/elementary/efl_ui_focus_parent_provider_standard.eo @segfaultxavi
  • src/lib/elementary/efl_ui_grid.eo @bu5hm4n DONE @segfaultxavi
  • src/lib/elementary/efl_ui_alert_popup.eo (@zmike)
  • src/lib/elementary/efl_ui_focus_manager_root_focus.eo @segfaultxavi
  • src/lib/elementary/efl_ui_group_item.eo @segfaultxavi
  • src/lib/elementary/efl_ui_list_default_item.eo @bu5hm4n DONE @segfaultxavi
  • src/lib/elementary/efl_ui_popup.eo (@zmike)
  • src/lib/elementary/efl_ui_grid_default_item.eo @segfaultxavi
  • src/lib/efl/interfaces/efl_gfx_arrangement.eo (@zmike)
  • src/lib/ecore/efl_boolean_model.eo (@myoungwoon) DONE @segfaultxavi
  • src/lib/ecore/efl_exe.eo (@akanad ) DONE @segfaultxavi
  • src/lib/elementary/efl_ui_focus_manager.eo (root, request_subchild, logical_end, dirty_logic_freeze) (@bu5hm4n) DONE @segfaultxavi
  • src/lib/elementary/efl_ui_focus_object.eo (setup_order) (@bu5hm4n) DONE @segfaultxavi
  • Replace Doxygen references like # with Eolian ones @. Locate files using find -name "*.eo" | xargs grep "#[a-zA-Z_]*" -l. For example, #EFL_UI_CLOCK_TYPE_YEAR --> @Efl.Ui.Clock_Type.year @segfaultxavi
  • No line should be longer than 120 characters. @segfaultxavi
  • src/lib/elementary/efl_ui_widget_scrollable_content.eo --> Missing @ tags (My comments on D9674 and D9676) @zmike

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
There are a very large number of changes, so older changes are hidden. Show Older Changes

Until T7736 or T6890 are resolved, doc references to particular Eina.Errors are complicated.

bu5hm4n updated the task description. (Show Details)Jul 31 2019, 2:14 AM
segfaultxavi updated the task description. (Show Details)Jul 31 2019, 7:46 AM
zmike added a comment.Aug 6 2019, 5:56 AM

All properties should have their default values defined (e.g., if it's a bool property then it should state whether the default is true or false). Ideally this should be REQUIRED by eolian.

segfaultxavi updated the task description. (Show Details)Mon, Aug 26, 9:27 AM
woohyun updated the task description. (Show Details)Mon, Aug 26, 10:42 PM
woohyun updated the task description. (Show Details)
woohyun updated the task description. (Show Details)
woohyun added subscribers: bowonryu, felipealmeida.
woohyun added a subscriber: bu5hm4n.

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)Tue, Aug 27, 7:56 AM
myoungwoon updated the task description. (Show Details)Wed, Aug 28, 1:05 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.

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)Wed, Aug 28, 1:26 AM
segfaultxavi updated the task description. (Show Details)Wed, Aug 28, 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)Wed, Aug 28, 11:29 PM
myoungwoon added subscribers: akanad, wc, eagleeye.
segfaultxavi updated the task description. (Show Details)Thu, Aug 29, 5:18 AM
myoungwoon updated the task description. (Show Details)Thu, Aug 29, 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)Fri, Aug 30, 3:04 AM
segfaultxavi updated the task description. (Show Details)Mon, Sep 2, 1:46 AM
segfaultxavi updated the task description. (Show Details)Mon, Sep 2, 2:59 AM
segfaultxavi updated the task description. (Show Details)Mon, Sep 2, 7:31 AM
segfaultxavi updated the task description. (Show Details)Tue, Sep 3, 2:47 AM
segfaultxavi updated the task description. (Show Details)Tue, Sep 3, 8:58 AM
segfaultxavi updated the task description. (Show Details)Tue, Sep 3, 10:27 AM
zmike updated the task description. (Show Details)Mon, Sep 9, 8:03 AM
zmike updated the task description. (Show Details)Mon, Sep 9, 11:21 AM
segfaultxavi updated the task description. (Show Details)Tue, Sep 10, 2:54 AM
segfaultxavi updated the task description. (Show Details)Tue, Sep 10, 4:02 AM
segfaultxavi updated the task description. (Show Details)Tue, Sep 10, 7:02 AM
segfaultxavi updated the task description. (Show Details)Tue, Sep 10, 8:15 AM
zmike updated the task description. (Show Details)Wed, Sep 11, 11:02 AM
segfaultxavi updated the task description. (Show Details)Thu, Sep 12, 2:30 AM
segfaultxavi updated the task description. (Show Details)Thu, Sep 12, 3:04 AM
segfaultxavi updated the task description. (Show Details)Thu, Sep 12, 3:08 AM
bu5hm4n updated the task description. (Show Details)Fri, Sep 13, 3:33 AM
zmike updated the task description. (Show Details)Fri, Sep 13, 8:31 AM
zmike updated the task description. (Show Details)Fri, Sep 13, 8:39 AM
zmike updated the task description. (Show Details)Fri, Sep 13, 8:42 AM
zmike updated the task description. (Show Details)
segfaultxavi updated the task description. (Show Details)Fri, Sep 13, 9:30 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.

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)Fri, Sep 13, 11:20 AM
CHAN added a subscriber: CHAN.Tue, Sep 17, 9:42 PM

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

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

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