feat: simplify the PR template (lvgl#5134)

OS-Q · Jan 2, 2024 · 8b1ae26 · 8b1ae26
1 parent 3cc2f99
commit 8b1ae26
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 64 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,27 +1,12 @@
+Help us review this PR! Anyone can [approve it or request changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews).
+
 ### Description of the feature or fix
 
 A clear and concise description of what the bug or new feature is.
 
 ### Checkpoints
-- [ ] Run `code-format.py` from the scripts folder. [astyle](http://astyle.sourceforge.net/install.html) needs to be installed.
-- [ ] Update the [Documentation](https://github.com/lvgl/lvgl/tree/master/docs) if needed
-- [ ] Add [Examples](https://github.com/lvgl/lvgl/tree/master/examples) if relevant. 
-- [ ] Add [Tests](https://github.com/lvgl/lvgl/blob/master/tests/README.md) if applicable.
-- [ ] If you added new options to `lv_conf_template.h` run [lv_conf_internal_gen.py](https://github.com/lvgl/lvgl/blob/release/v8.3/scripts/lv_conf_internal_gen.py) and update [Kconfig](https://github.com/lvgl/lvgl/blob/release/v8.3/Kconfig).
-
-Be sure the following conventions are followed:
-- [ ] Follow the [Styling guide](https://github.com/lvgl/lvgl/blob/master/docs/CODING_STYLE.md)
-- [ ] Prefer `enum`s instead of macros. If inevitable to use `define`s export them with `LV_EXPORT_CONST_INT(defined_value)` right after the `define`.
-- [ ] In function arguments prefer `type name[]` declaration for array parameters instead of `type * name`
-- [ ] Use typed pointers instead of `void *` pointers
-- [ ] Do not `malloc` into a static or global variables. Instead declare the variable in `lv_global_t` structure in [`lv_global.h`](https://github.com/lvgl/lvgl/blob/master/src/core/lv_global.h) and mark the variable with `(LV_GLOBAL_DEFAULT()->variable)` when it's used. See a detailed description [here](https://docs.lvgl.io/master/get-started/bindings/micropython.html#memory-management).
-- [ ] Widget constructor must follow the `lv_<widget_name>_create(lv_obj_t * parent)` pattern.
-- [ ] Widget members function must start with `lv_<module_name>` and should receive `lv_obj_t *` as first argument which is a pointer to widget object itself.  
-- [ ] `struct`s should be used via an API and not modified directly via their elements.
-- [ ] `struct` APIs should follow the widgets' conventions. That is to receive a pointer to the `struct` as the first argument, and the prefix of the `struct` name should be used as the prefix of the function name too (e.g.  `lv_disp_set_default(lv_disp_t * disp)`)
-- [ ] Functions and `struct`s which are not part of the public API must begin with underscore in order to mark them as "private".
-- [ ] Arguments must be named in H files too.
-- [ ] To register and use callbacks one of the following needs to be followed (see a detailed description [here](https://docs.lvgl.io/master/get-started/bindings/micropython.html#callbacks)):
-  - For both the registration function and the callback pass a pointer to a `struct` as the first argument. The `struct` must contain `void * user_data` field.
-  - The last argument of the registration function must be `void * user_data` and the same `user_data` needs to be passed as the last argument of the callback.
-  - Callback types not following these conventions should end with `xcb_t`.
+- Update the [Documentation](https://github.com/lvgl/lvgl/tree/master/docs) if needed.
+- Add [Examples](https://github.com/lvgl/lvgl/tree/master/examples) if relevant.
+- Add [Tests](https://github.com/lvgl/lvgl/blob/master/tests/README.md) if applicable.
+- If you added new options to `lv_conf_template.h` run [lv_conf_internal_gen.py](https://github.com/lvgl/lvgl/blob/master/scripts/lv_conf_internal_gen.py) and update [Kconfig](https://github.com/lvgl/lvgl/blob/master/Kconfig).
+- Run `scripts/code-format.py` ([astyle](http://astyle.sourceforge.net/install.html) needs to be installed) and follow the [Code Conventions](https://docs.lvgl.io/master/CODING_STYLE.html)
diff --git a/docs/CODING_STYLE.rst b/docs/CODING_STYLE.rst
@@ -1,8 +1,8 @@
 Coding style
 ============
 
-File format
------------
+File template
+-------------
 
 Use `misc/lv_templ.c <https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.c>`__
 and `misc/lv_templ.h <https://github.com/lvgl/lvgl/blob/master/src/misc/lv_templ.h>`__
@@ -18,8 +18,8 @@ Naming conventions
 -  Global names (API):
 
    -  start with *lv*
-   -  followed by module name: *btn*, *label*, *style* etc.
-   -  followed by the action (for functions): *set*, *get*, *refr* etc.
+   -  followed by module name: *button*, *label*, *style* etc.
+   -  followed by the action (for functions): *set*, *get*, etc.
    -  closed with the subject: *name*, *size*, *state* etc.
 
 -  Typedefs
@@ -31,18 +31,27 @@ Naming conventions
 
 -  Abbreviations:
 
-   -  Only words longer or equal than 6 characters can be abbreviated.
-   -  Abbreviate only if it makes the word at least half as long
-   -  Use only very straightforward and well-known abbreviations
-      (e.g. pos: position, def: default, btn: button)
+   -  The following abbreviations are used and allowed:
+
+      - ``dsc`` descriptor
+      - ``param`` parameter
+      - ``indev`` input device
+      - ``anim`` animation
+      - ``buf``  buffer
+      - ``str`` string
+      - ``min/max`` minimum/maximum
+      - ``alloc`` allocate
+      - ``ctrl`` control
+      - ``pos`` position
+   -  Avoid adding new abbreviations
 
 Coding guide
 ------------
 
 -  Functions:
 
-   -  Try to write function shorter than is 50 lines
-   -  Always shorter than 200 lines (except very straightforwards)
+   -  Write function with single responsibility
+   -  Make the functions ``static`` where possible
 
 -  Variables:
 
@@ -57,7 +66,7 @@ Coding guide
 Comments
 --------
 
-Before every function have a comment like this:
+Before every function have in ``.h`` files a comment like this:
 
 .. code:: c
 
@@ -66,7 +75,7 @@ Before every function have a comment like this:
     * @param obj pointer to an object
     * @return pointer to a screen
     */
-   lv_obj_t * lv_obj_get_scr(lv_obj_t * obj);
+   lv_obj_t * lv_obj_get_screen(lv_obj_t * obj);
 
 Always use ``/*Something*/`` format and NOT ``//Something``
 
@@ -83,6 +92,38 @@ Short "code summaries" of a few lines are accepted. E.g.
 In comments use \` \` when referring to a variable. E.g.
 :literal:`/\*Update the value of \`x_act`*/`
 
+
+API Conventions
+----------------------
+
+To support the auto-generation of bindings, the LVGL C API must
+follow some coding conventions:
+
+- Use ``enum``\ s instead of macros. If inevitable to use ``define``\ s
+  export them with :cpp:expr:`LV_EXPORT_CONST_INT(defined_value)` right after the ``define``.
+- In function arguments use ``type name[]`` declaration for array parameters instead of :cpp:expr:`type * name`
+- Use typed pointers instead of :cpp:expr:`void *` pointers
+- Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern.
+- Widget members function must start with ``lv_<widget_name>`` and should receive :cpp:expr:`lv_obj_t *` as first
+  argument which is a pointer to widget object itself.
+- ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the
+  first argument, and the prefix of the ``struct`` name should be used as the prefix of the
+  function name too (e.g. :cpp:expr:`lv_disp_set_default(lv_disp_t * disp)`)
+- Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as "private".
+- Argument must be named in H files too.
+- Do not ``malloc`` into a static or global variables. Instead declare the variable in ``lv_global_t``
+  structure in ``lv_global.h`` and mark the variable with :cpp:expr:`(LV_GLOBAL_DEFAULT()->variable)` when it's used.
+- To register and use callbacks one of the following needs to be followed.
+
+   - Pass a pointer to a ``struct`` as the first argument of both the registration function and the callback. That
+     ``struct`` must contain ``void * user_data`` field.
+   - The last argument of the registration function must be ``void * user_data`` and the same ``user_data``
+     needs to be passed as the last argument of the callback.
+
+
+To learn more refer to the documentation of `MicroPython <integration/bindings/micropython>`__.
+
+
 Formatting
 ----------
 

diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -145,8 +145,9 @@ div.body {
 }
 
 .cpp-expr {
-  font-family: monospace;
-  background-color: #dff0ff;
-  padding: 1px;
-  border-radius: 4px;
+  font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;
+  color: #e74c3c;
+  padding: 2px 5px;
+  border: 1px solid #e1e4e5;
+  font-size: 75%;
 }
diff --git a/docs/integration/bindings/micropython.rst b/docs/integration/bindings/micropython.rst
@@ -179,32 +179,7 @@ The Micropython Binding is auto generated!
 LVGL C API Coding Conventions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To support the auto-generation of the Python API, the LVGL C API must
-follow some coding conventions:
-
-- Use ``enum``\ s instead of macros. If inevitable to use ``define``\ s
-  export them with :cpp:expr:`LV_EXPORT_CONST_INT(defined_value)` right after the ``define``.
-- In function arguments use ``type name[]`` declaration for array parameters instead of :cpp:expr:`type * name`
-- Use typed pointers instead of :cpp:expr:`void *` pointers
-- Widget constructor must follow the ``lv_<widget_name>_create(lv_obj_t * parent)`` pattern.
-- Widget members function must start with ``lv_<module_name>`` and should receive :cpp:expr:`lv_obj_t *` as first
-  argument which is a pointer to widget object itself.
-- ``struct`` APIs should follow the widgets' conventions. That is to receive a pointer to the ``struct`` as the
-  first argument, and the prefix of the ``struct`` name should be used as the prefix of the
-  function name too (e.g. :cpp:expr:`lv_disp_set_default(lv_disp_t * disp)`)
-- Functions and ``struct``\ s which are not part of the public API must begin with underscore in order to mark them as "private".
-- Argument must be named in H files too.
-- Do not ``malloc`` into a static or global variables. Instead declare the variable in ``lv_global_t``
-  structure in ``lv_global.h`` and mark the variable with :cpp:expr:`(LV_GLOBAL_DEFAULT()->variable)` when it's used. **See** :ref:`memory_management`
-- To register and use callbacks one of the following needs to be followed.  **See** :ref:`callbacks`
-
-   - Pass a pointer to a ``struct`` as the first argument of both the registration function and the callback. That
-     ``struct`` must contain ``void * user_data`` field.
-   - The last argument of the registration function must be ``void * user_data`` and the same ``user_data``
-     needs to be passed as the last argument of the callback.
-
-Most of these rules are simple and straightforward but there are two related concepts that worth a deeper look:
-:ref:`memory_management` and :ref:`callbacks`.
+For a summary of coding conventions to follow see the `CODING STYLE <CODING_STYLE>`__.
 
 .. _memory_management: