Hi, Gabor! ( @kisvegabor )

I submitted this one separately so you could have a look at it in an easier way than in the #6480 issue.

Once we get the details of this sorted (or if you like it as it is), I suggest we start a new project, perhaps under issue #6671 "Add missing documentation", and make these modifications to some of the core part of the library to set an example.

This contains 2 changes:

• The original "Comments" section is mostly preserved except that I replaced the original comment example with a better one, and adjusted the existing example comments to reflect (what I think is) current guidance for more readable in-source comments as well as more readable generated documentation. I also added (at the bottom) a little bit of insightful wisdom that makes code so much more readable and maintainable from the great Donald Knuth (author of The Art of Computer Programming, among other things).
• I added a new section called "Doxygen Comment Specifics" just below the original "Comments" section, and tried to keep it as short as possible.

In the "Doxygen Comment Specifics" section, I left the @file command argument (the file's name) in place for consistency with the rest of the library. While it is redundant (Doxygen doesn't need it), it does no harm -- as long as the name stays the same as the filename. When the filename changes, however, Doxygen silently stops outputting documentation for that file, so I have an idea for a future improvement, but will skip the details here.

Over to you. I hope you like it. FYI I am kind of on a Europe schedule right now to give us more common time on our schedules (why you have seen me posting things very early).

Kind regards,
Vic

Thank you Vic. I've added my initial comments .

Thank you Vic. I've added my initial comments .

Hi, Gabor! I've realized that introducing /** and /**< really need to be early in the comments section, so I am re-working the introduction a bit so as to introduce the subject of comments more gracefully. (I was initially trying to "avoid" changing the original "Comments" section much, but I see now that it should be adjusted a bit since Doxygen comments otherwise go unexplained until the next section.) Will re-push as soon as I have it ready.

@kisvegabor Okay. Re-submitted. I found I needed to run it through sphinx to really see what it was going to look like, and in doing so, I not only found quite a few things that needed to be adjusted, but realized that you would need to see this too. So here is [the link] so you can see what I see, and can compare them side by side if needed.

In case you were not already aware, the leading "|" in lines tell ReStructuredText where to line wrap, when it is important. Thus:

| something here
| this needs to be on its own line

comes out the same way as this in HTML:

something here<br>
this needs to be on its own line

I used that in a couple of cases to make it more readable.

I also:

1. removed the paragraph numbers, since it was inconsistent with the rest of the document,
2. corrected one typo early in the document, which you will see in the changes, and
3. rebased my branch on current master as of a few minutes ago.

@kisvegabor Hi, Gabor! Ready for re-review/approval/merging.

Thank you! I can review it next week.

Thank you! I can review it next week.

Okay.

Hi, Gabor! ( @kisvegabor )

This is just a reminder that the view of the CODING_STYLE.rst file after sphinx has processed it is here.

I feel like it's a little bit lengthy and developers might not read it.

Great points, and I really like your attention to brevity! I know in this world, compactness (brevity, succinctness) is very helpful. Historically, a 2nd pair of eyes helps me to not get carried away, where half the number of words (or less, or an illustration) can carry the same meaning faster. I will work on this.

Hi, Gábor! ( @kisvegabor )

Okay, I have re-submitted. Here is what the document now looks like after it has been run through sphinx with the Read-the-Docs theme (same as is used in LVGL generated documentation).

Things that we did not discuss above:

1. Using 4 spaces instead of tabs is something that should be understood by programmers before they even start editing anything, and it was previously way at the end of the document. So I moved it near the beginning under a small "Editor" item in the Coding guide section. That way it is very clear that programmers that use TABs should change their editor configurations before making changes to LVGL code.
2. I moved the detailed example down to the Doxygen Comment Specifics subsection, next to the bullet points that explain the various parts of the example.
3. While it may be clear about most of the Doxygen commands that are supported, I added (as a new Supported Doxygen Commands sub-section) the list of the Doxygen commands that can be freely used in LVGL code, to be explicitly clear that the list of accepted Doxygen commands is limited. To be frank, I find that list section uncomfortably long (since we are stressing brevity). Perhaps I could make it into another bullet list and simply place links to the Doxygen documentation page#anchor where it is covered, and remove the descriptions? Like this:

• @file [web link]
• @param [web link]
• etc.

I placed additional "Do not ..." information with the @ref command, which does need to be preserved, however, because many programmers have used the @ref command in front of function and type names thinking that would produce a hyperlink to their documentation, but it doesn't—it generates a Doxygen warning and no hyperlink is generated! So I explained the correct way of using it. I could make that explanation into a "note" if we reduce the list to a bullet list as above.

Kevin ( @kdschlosser ), you may be pleased to know that I removed the "rare" ones from the list we previously discussed, so it is now down to:

• @file
• @param
• @return
• @code/@endcode
• @note
• @anchor
• @ref
• @see

And I didn't mention the > or >> at all since, for the one case we encountered—it should not have been used.

:-)

Kind regards,
Vic

the @anchor doesn't transfer over to the ReST side of things. The only thing that Sphinx is able to create anchors for are headings.

This is how a heading gets anchored in Sphinx

.. _some_heading_anchor:

Some Heading
---------------

so having anchors in the API documentation is not going to get linked to properly when referencing an anchor.

The other thing that should be done is to see if the anchors are even being used.... If they are then maybe changing the reference to that anchor to something that is able to be referenced in Sphinx like the object that has the documentation that is wanting to be referenced.

also with the @code directive, we need to change those so they have an explicit code type set...

@code{.c}
@code{.py}
...

Here is a complete list of extensions you can use...

https://pygments.org/languages/

what would actually be better than supplying the file extension is supplying the short name...

it can be one of the following names...

Thanks! I still see a little redundancy here and there, but it should be okay now.

@anchor and @ref really seems overkill. I think for the sake of simplicity we should be fine without them too.

the @anchor doesn't transfer over to the ReST side of things.

cc: @kisvegabor

In reality, there is probably no good reason to keep @anchor and @ref, and we are blessed by the fact that NOT including @ref in the list will, by itself, tell programmers not to use it—which will take care of the 50 or so mis-uses of it I found and corrected (they were generating Doxygen warnings).

I will adjust the document accordingly.

About @code: there are no @code/@endcode in LVGL blocks that use anything besides C, so I believe the C language can be assumed from now until code blocks with different languages show up. But that said, Kevin, do we get an "automatic" code highlighting from spinx by having the {.c} part in there? (The difference in the XML generated is that the <programlisting> element gets a filename=".c" attribute, but doesn't without it.) Or does sphinx already know how to do code highlighting for code blocks from the context?

@kdschlosser @kisvegabor

Okay! Re-submitted. I believe that takes care of everything we have discussed up to this point, but the question about the {.c} appendage to the @code command remains outstanding. Meanwhile, the content of CODING_STYLE.rst is safe. That bit about the {.c} appendage to the @code command can be modified later if need be.

And this document is updated to show the "after-sphinx" appearance.

When I finish up with the script that hopefully will replace Breathe we will be given the ability to use ReST syntax directly in the doxygen docstrings. If there is some need to reference other areas of the documentation it will be as easy as ":ref:`some_reference_name`" and if wanting to reference something in doxygen docstrings it will be one of the following...

• ":c:macro:`some_macro`"
• ":c:struct:`some_struct`"
• ":c:union:`some_union`"
• ":c:type:`some_type`"
• ":c:member:`some_struct::some_member`"
• ":c:member:`some_union::some_member`"
• ":c:var:`some_var`"
• ":c:function:`some_function`"

I created a development discussion issue for a Breathe replacement. This is mostly for me to be able to remember how things are supposed to work and what I need to do to make things work.

#6770

If there is some need to reference other areas of the documentation it will be as easy as ":ref:some_reference_name" and if wanting to reference something in doxygen docstrings it will be one of the following...

Very nice!! Got it regarding the Breathe replacement issue #6770.

Hi, Gábor! ( @kisvegabor )

An indicated off-shoot of modifying CODING_STYLE.rst is buzzing through ./src/core/ and probably ./src/misc/ and ./src/widget/ and apply these rules to set a good example. I don't think it would take that long. What do you think?

Kind regards,
Vic

@liamHowatt @kisvegabor Liam had some great observations. I agreed with all, and have re-submitted, and updated the generated demonstration document with the updates.

I did find out something with doxygen. It will NOT add a "brief description" unless you specifically use the @brief directive.

I did find out something with doxygen. It will NOT add a "brief description" unless you specifically use the @brief directive.

Hi, Kevin!
2 questions:

1. Does anything go missing without them?
2. Does it enhance the final output to have them?

don't know the answer to either of those questions as I have never tested it. I do know that the "briefdescription" element in the XML only seems to get populated when the @brief command is used. Breathe might format a brief description differently.
¯\_(ツ)_/¯

@liamHowatt Good morning! I could use your approval on this again now that I have re-submitted. :-)

Thank you!

Thank you, Vic!