Page MenuHome

Improve structure and visual identity in Doxygen comments in- and out -of code. Without structure ... entropy.
Confirmed, NormalPublicDESIGN

Description

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!

Revisions and Commits

Event Timeline

@Jonas Printzén (ZPU)
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:

  1. Not using Doxygen to anywhere near its potential. You have essayed this task to address that
  2. 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 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.

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.

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.

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.

@Aaron Carlisle (Blendify), @Garry R. Osgood (grosgood)

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

Cheers!

Patch D6625 created.

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

@Jonas Printzén (ZPU)

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 @Campbell Barton (campbellbarton) 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 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.

Hi @Jonas Printzén (ZPU), 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 (campbellbarton) changed the task status from Needs Triage to Confirmed.Wed, Feb 12, 8:53 AM
Campbell Barton (campbellbarton) changed the subtype of this task from "Report" to "Design".

My absence is forced.
Will return and simplify according to feedback.