Improve structure and visual identity in Doxygen comments in- and out -of code. Without structure ... entropy. #73140

New Issue

Jonas Printzén · 2020-01-15T16:15:42+01:00

Jonas Printzén commented

2020-01-15 16:15:42 +01:00

Building the Doxygen material today and attempting to use it for whatever purpose is not completely working.
The structure is collapsed to long lists of pages and modules not easily readable. The reason is how doxygen tags are used.

It is an essential value that goes missing, since there are a lot of good information there but it is not easy to navigate.

Note! The structure can be built and refined separately from the in depth information as long as clear examples to follow exist

I propose to:

Move the existing material from groups (defgroup/ingroup) to pages and sections to release the short-cirquit.

  This will still be available in "Related pages"

Create a proper informative and navigation-friendly structure in the Mainpage and Modules (groups)
Create a proper visual identity so we all recognize it as blender content
Add new and existing material to the structure and start refining reviews for consistence.
Connect the Doxygen material with online material, both ways if possible, to maximize information value.

The result is a structure that explains itself and therefore, with a little review-help, continuously improves instead of decays.

I have started but not contributed yet, please promote this task!

Building the **Doxygen** material today and attempting to use it for whatever purpose is not completely working. The structure is collapsed to long lists of pages and modules not easily readable. The reason is how doxygen tags are used. It is an essential value that goes missing, since there are a lot of good information there but it is not easy to navigate. > **Note!** The structure can be built and refined separately from the in depth information as long as clear examples to follow exist I propose to: 1) Move the existing material from groups (defgroup/ingroup) to pages and sections to release the short-cirquit. ``` This will still be available in "Related pages" ``` 2) Create a proper informative and navigation-friendly structure in the **Mainpage** and **Modules** (groups) 3) Create a proper visual identity so we all recognize it as blender content 4) Add **new** and **existing** material to the structure and start refining reviews for consistence. 5) Connect the Doxygen material with online material, both ways if possible, to maximize information value. The result is a structure that explains itself and therefore, with a little review-help, continuously improves instead of decays. I have started but not contributed yet, please promote this task! ![BlendDoxMain.png](https://archive.blender.org/developer/F8279818/BlendDoxMain.png)

Jonas Printzén commented

2020-01-15 16:15:42 +01:00

Added subscriber: @JonasPrintzen

Jonas Printzén self-assigned this 2020-01-15 16:34:55 +01:00

Garry R. Osgood commented

2020-01-16 13:49:50 +01:00

Added subscriber: @grosgood

Garry R. Osgood commented

2020-01-16 13:49:50 +01:00

@JonasPrintzen
Welcome to the project. I trust you have gone through the Build Blender exercise, have issued ##make doc_doxy## and have been disenchanted with the result. In my opinion, this is a consequence of:

Not using Doxygen to anywhere near its potential. You have essayed this task to address that
The process of writing code level templates - Doxygen's input - have largely been bypassed by the protocols attending submitting a diff patch , which has a documentation component as well. This has effectively cut off the air supply to Doxygen.
As to the first point, I think this task is more at the design - todo level, meaning it is of the more ambitious sort. [Cambell's suggestions ]] about keeping your first efforts focused on a individually manageable effort is key: one or two pilot templates to illustrate Doxygen's potential to the community at large may be a more realistic scoping for this task. My second point is in play, because this community already has a way to deliver code documentation to the project through [ https:*devtalk.blender.org/t/feature-patch-description-requirements/10775/21|diff patches , which translate to commit messages and become metadata in the code repository - documentation about code, and automagically linked to the code in the repository. "And now you want us to write templates too??". may very well be the protest here. To that extent, the very idea of including templated code documentation would have to be argued here. That is beyond the scope of this task, but I think it is the 800 lb. gorilla currently sitting in the room.
However you scope this task, I hope you stay at it in some form or another. Literate programmers are few and far in between. Every project could use a couple.

@JonasPrintzen Welcome to the project. I trust you have gone through the [Build Blender ](https://wiki.blender.org/wiki/Building_Blender) exercise, have issued ##make doc_doxy## and have been disenchanted with the result. In my opinion, this is a consequence of: - Not using Doxygen to anywhere near its potential. You have essayed this task to address that - The process of writing code level templates - Doxygen's input - have largely been bypassed by the protocols attending [submitting a diff patch ](https://wiki.blender.org/wiki/Process/Contributing_Code), which has a documentation component as well. This has effectively cut off the air supply to Doxygen. As to the first point, I think this task is more at the design - todo level, meaning it is of the more ambitious sort. [Cambell's suggestions ]] about keeping your first efforts focused on a individually manageable effort is key: one or two pilot templates to illustrate Doxygen's potential to the community at large may be a more realistic scoping for this task. My second point is in play, because this community already has a way to deliver code documentation to the project through [[ https:*devtalk.blender.org/t/feature-patch-description-requirements/10775/21|diff patches ](https:*devtalk.blender.org/t/id-like-to-help-improve-the-use-of-doxygen-in-blender-main-source/11176/6?u=grosgood), which translate to commit messages and become metadata in the code repository - documentation about code, and automagically linked to the code in the repository. "*And now you want us to write templates too??*". may very well be the protest here. To that extent, the very idea of including templated code documentation would have to be argued here. That is beyond the scope of this task, but I think it is the 800 lb. gorilla currently sitting in the room. However you scope this task, I hope you stay at it in some form or another. Literate programmers are few and far in between. Every project could use a couple.

Aaron Carlisle commented

2020-01-18 22:21:10 +01:00

Added subscribers: @jesterking, @dfelinto, @ideasman42

Jonas Printzén commented

2020-01-19 00:30:43 +01:00

I am thinking about a small scope adjustment or clarification based on diverse input.

First I set the structure that makes navigation a nice experience.

  This I can do with just adding layout, CSS and a few grouping structures.

To respect the work that has already been done, I can move the 'lists' one level down.

   That way you will see the structured breakdown grow while still having the old available.

Selectively interact with those who provided the material that is easiest to fit in the structure.

My goal should be to figure out how to make it so compelling to use that it makes more sense
to put your thoughts about API and structure in the Doxygen form than another. I will provide
examples of the 5 archetypes I have in mind by documenting what I can and ask for feedback.

With a little effort there will be examples easy enough to follow ...

Planning to submit a patch with the first structure and visual setup within a day or two.

I am thinking about a small scope adjustment or clarification based on diverse input. 1) First I set the structure that makes navigation a nice experience. ``` This I can do with just adding layout, CSS and a few grouping structures. ``` 2) To respect the work that has already been done, I can move the 'lists' one level down. ``` That way you will see the structured breakdown grow while still having the old available. ``` 3) Selectively interact with those who provided the material that is easiest to fit in the structure. My goal should be to figure out how to make it so compelling to use that it makes more sense to put your thoughts about API and structure in the Doxygen form than another. I will provide examples of the 5 archetypes I have in mind by documenting what I can and ask for feedback. With a little effort there will be examples easy enough to follow ... Planning to submit a patch with the first structure and visual setup within a day or two.

Aaron Carlisle commented

2020-01-19 01:01:48 +01:00

Added subscriber: @Blendify

Aaron Carlisle commented

2020-01-19 01:01:48 +01:00

That sounds great I am excited to see what will come of this. I think if you help provide a good structure and good examples. Other developers will be more likely to use doxygen and we can "inforce" to patches to properly document code.

Jonas Printzén commented

2020-01-19 17:49:56 +01:00

Ready with a first patch to get visuals and some structure in place.
I have been reading about submitting patches and tried the page https://developer.blender.org/differential/diff/create/ but I can't answer all questions needed to get through the process.

EDITED: Now I think I managed to create a diff, D6625.

@Blendify, @grosgood

My patch touches only ./doc/doxygen and comments in three other headers for examples.

Cheers!

Ready with a first patch to get visuals and some structure in place. I have been reading about submitting patches and tried the page https://developer.blender.org/differential/diff/create/ but I can't answer all questions needed to get through the process. EDITED: Now I think I managed to create a diff, [D6625](https://archive.blender.org/developer/D6625). @Blendify, @grosgood My patch touches only ./doc/doxygen and comments in three other headers for examples. Cheers!

Jonas Printzén commented

2020-01-19 19:36:49 +01:00

Patch D6625 created.

Question:
I am trying to bind the patch D6625 to this issue. I can't find it.
Hint's anone?

Patch [D6625](https://archive.blender.org/developer/D6625) created. Question: I am trying to bind the patch [D6625](https://archive.blender.org/developer/D6625) to this issue. I can't find it. Hint's anone?

Garry R. Osgood commented

2020-01-19 22:53:54 +01:00

@JonasPrintzen

I am trying to bind the patch...

Forgive me. I am being dense over your terminology. I don't understand "bind the patch to this issue."
By "bind" do you mean "cross reference"? Perhaps it wasn't clear when you were in the midst of writing your last comment, but cross-references to the differential and this task were automatically created. Notations like ##Tnnnnn## and ##Dnnnn## are translated into HTML links to the target items. The 'book' icon in the banner of the text editor box, second from the right, places The Remarkup Reference Guide in another browser window. Then you can do all kinds of tricks in comments.

I can't fathom what you might mean otherwise.

I note you made me a reviewer to the D6625. I would recommend @ideasman42 instead. Target file [Doxyfile ]] has been recently touched by a number of his commits, which makes him an 'interested party.' In contrast, I do not have a great deal of practical experience with Doxygen. Familiarize yourself with the source listings in [ https:*developer.blender.org/diffusion/|Diffusion if you haven't already done so. That place maps lines of code to the changing commits - and, by extension, who did the commits. If you are not sure who to invite for a review on a Differential, Diffusion will give you hints by telling you whose recent commits have changed the file. Ditto ##git blame## and ##git log -L ...##.

Good work. Looking forward to what develops here.

@JonasPrintzen > I am trying to bind the patch... Forgive me. I am being dense over your terminology. I don't understand "bind the patch to this issue." By "bind" do you mean "cross reference"? Perhaps it wasn't clear when you were in the midst of writing your last comment, but cross-references to the differential and this task were automatically created. Notations like ##Tnnnnn## and ##Dnnnn## are translated into HTML links to the target items. The 'book' icon in the banner of the text editor box, second from the right, places [The Remarkup Reference Guide ](https://secure.phabricator.com/book/phabricator/article/remarkup/) in another browser window. Then you can do all kinds of tricks in comments. I can't fathom what you might mean otherwise. I note you made me a reviewer to the [D6625](https://archive.blender.org/developer/D6625). I would recommend @ideasman42 instead. Target file [Doxyfile ]] has been recently touched by a number of his commits, which makes him an 'interested party.' In contrast, I do not have a great deal of practical experience with Doxygen. Familiarize yourself with the source listings in [[ https:*developer.blender.org/diffusion/|Diffusion ](https:*developer.blender.org/diffusion/B/browse/master/doc/doxygen/Doxyfile$1) if you haven't already done so. That place maps lines of code to the changing commits - and, by extension, who did the commits. If you are not sure who to invite for a review on a Differential, Diffusion will give you hints by telling you whose recent commits have changed the file. Ditto ##git blame## and ##git log -L ...##. Good work. Looking forward to what develops here.

Aaron Carlisle commented

2020-01-19 23:10:30 +01:00

Hi @JonasPrintzen, thanks for submitting the patch the way you did it correctly. I bound the differential to the task for you. You can do this from the revision: Edit Related Objects --> Edit Tasks...

Hi @JonasPrintzen, thanks for submitting the patch the way you did it correctly. I bound the differential to the task for you. You can do this from the revision: `Edit Related Objects --> Edit Tasks...`

Campbell Barton commented

2020-02-12 08:53:27 +01:00

Changed status from 'Needs Triage' to: 'Confirmed'