diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f5dc413caa..e88f258ca9 100644 --- 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__create(lv_obj_t * parent)` pattern. -- [ ] Widget members function must start with `lv_` 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 index 749ab8d9e7..65c1f1a79a 100644 --- 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 `__ and `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__create(lv_obj_t * parent)`` pattern. +- Widget members function must start with ``lv_`` 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 `__. + + Formatting ---------- diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 18507d0260..3ba929965c 100644 --- 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 index 2d6535f25e..57d3a07877 100644 --- 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__create(lv_obj_t * parent)`` pattern. -- Widget members function must start with ``lv_`` 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 `__. .. _memory_management: