Hi All!
Edited
I’m interested in what happens to code-documentation. Specifically the doxygen stuff actually right in the code. I’ve seen a few dummy-headers containing only sections pages and such things. Is there anyone who is/feels responsible for the strategy using doxygen?
I have some experience and would love to help.
There isn’t a special code-documentation effort per se. The most benefit for documentation of code would be in the architectural documentation of Blender, and of the modules in Blender. Some of this is done in https://wiki.blender.org/wiki/Source , but still lots of room for improvement. Perhaps it is best to get started with that.
There isn’t a clear policy on doxygen comments in code, from what I can tell not even for new patches and so on. It’d be a nice part to have, though. Maybe @dfelinto could incorporate that as part of the patch review process document he’s got.
So far @ideasman42 has lead the doxygen efforts in Blender. Campbell do you have any thing written down regarding plans for someone to pick up on that?
Thanx for replying @jesterKing
I like the fact that there is basically nothing there yet. It’s a great opportunity to inject some navigation-friendly breakdown to the code-base. I’ve used this many times as a consultant when helping companies (ABB, SAAB, E///, Boeing, BB) to improve or adopt agile, CI or DevOps.
But there are many ways to do it and this belong in an overall documentation context and since I’m new here I’m still navigating the big picture.
I see some smells (points of improvement) in the current documentation but that’s also to early. I need better understanding of the whole and who does what. Still, I’m probably ready soon to propose some kind of brief draft for a documentations strategy if nothing exists already.
I just thought I’d end my my prolonged holidays with an example of documentation draft I’ve used. It’s incomplete and I’ve typically used it to kick start the discussions…
Keep it as simple as possible, but not simpler.
Don’t panic. (I’l eventually write an AI to do the documentation., until then…)
Make it simpler if you can and your grandma still understands
Stop complaining, the AI isn’t done yet!
For documentation to be as useful as possible, it needs to fill a well-defined and well-known purpose. The concept Cohesion, well-known from a multitude of scientific disciplines, is just as applicable to documentation.
So, the foundation of course is:
Types of documentation:
| Type | Primary audience | Language | Notes |
|---|---|---|---|
| Product documentation | Sales | Glossy! TR? ( Impress, don’t promise  ) |
|
| User manual | End users AddonDev | Entirely in the domain of the user/application. Models, materials, animation. Illustrated brief document. | (TODO: What’s the penalty for words like recursion,subclass,operator) |
| Requirements | Designers Integrators Testers AddonDev CppDev | Domain language. A number of short descriptions of what the user expects. The most important non-functionals. | (Special penalty for ‘re-entrant’) |
| (Sys/SW) Architecture Design | Designers Integrators Testers CppDev Developers | Mix of Domain and software outline terms. Illustrated view of the System/Software. Only outline level to keep it’s size digestible. Use references to other docs | |
| API Dox | Designers CppDev AddonDev | Software engineering terms with reference to domain and requirements. Preferably generated documentation from source. Close to every function so as to enable synchronising when changing. |
.
Note! These documents should refer to each other correctly to avoid bullimic docs and repetition.
There’s no problem with recursion here. (see ‘Rule number one and two’)
.
)… I said glossy, right?
TBD
Hi, thanks for the offer to help improve doxygen documentation.
Currently we’re using doxygen as follows.
\file).source/blender/makesdna/DNA_meshdata_types.h).source/blender/blenlib/intern/BLI_ghash.c).source/blender/bmesh/bmesh.h, source/blender/windowmanager/WM_types.h)So far we’re not especially concerned with generating a complete document.
As for your proposal, it’s quite high level,
and while the principle may be agreed on by all, there are some pitfalls to avoid…
Suggestions:
Start on this at a smaller scale (but keep the big picture in mind).
Contact a developer who can work with you and review/apply your changes.
Take a smaller section of code, and bring this up to a standard you
think is a good example for other modules to follow.
If you think there are some top-level re-organization that’s needed.
that could be OK as long as you separate this from more detailed
changes so we don’t have the problem of patches becoming too big to practically review.
Finally, it may be that your plans for the documentation have a much larger scope
then developers currently are able to spend time on.
So I think it’s best to start this on a smaller scale, then we can re-evaluate things along the way.
Feel free to join https://blender.chat #blendercoders room & ping me, or see if other devs have areas they would like help with.
Hello @ideasman42!
Thanks for replying!
I totally agree about taking small steps. I generally believe in minimalism and patience.
Is there an online version of the use-pattern you describe above? I think it needs some more concrete points to actually provide guidance and focus. As a long time hard-core developer I to do appreciate structure before detail. And also minimalism and Cohesion.
Sometimes the difference between success and failure is a few words in the right spot.
The example of guidelines for documentation was mostly to provoke dialog
I was just hoping to:
My favorite scenario would be to at least find some fundamental agreement on how to get the most of the structure created in Doxygen, to minimize maintenance issues and establish a chain where Doxygen comments in the code refer to the right architectural/design. Then dig a little deeper into and provide both architecture and API documentation for GHOST <–> WM <–> Operators to get the crisp comprehension I think we all appreciate.
But I must say that what I see in terms of Doxygen usage currently, is inconsistent and closer to the anti-patterns I’ve experienced (painfully) than success patterns. I have sufficient experience with both successful and failed uses of Doxygen to be a bit worried for the right reasons. Is documentation about files and their structure really primary and useful to understand API’s? My experience is that this is a beginners mistake.
In fact, today on my assignment at a large international company, I got involved with similar issues. Their approach was inconsistent, varying between awkward and heavy to maintain and just a backwards waist of time. There are many similarities to what I see in blender…
As an example, I’ve found that @file is the least valuable of the tags, while @(def|addto|in)group, @section and @page is the most valuable, in that order.
It’s all about what happens in the long run with or without a well defined purpose.
… and of course, how to provoke a discussion without sounding negative. I really can provide good examples for further analysis. I will try to show that with an example of what it would look like.
Currently \file is used to give a short explanation about what the file is for, so someone unfamiliar with the codebase gets some context. If we didn’t use this doxygen tag we would probably still want a few lines at the top of the file noting it’s purpose.
That’s not a replacement for API docs though.
Not sure what to make of your other comments since I don’t especially find doxygen heavy to maintain, I rather focus on concrete examples.
Are there existing projects you can point to which are good references?
You’re right @ideasman42.
I started a discussion that’s more appropriate when you have face-time.
Unfortunately my best examples are proprietary stuff from work… can’t share.
Planning to give an example based on blender-code. I’l look for publicly
available examples to compare with. It’l have to wait until this weekend though.
In the meantime, this is full of examples…
Cheers!
It would make the Doxygen output so much more valuable if it where structured for navigation and guidance. I’m sure this could also be made more compelling to contribute to. Trying to visually harmonize with blender.org main-page as well.
I wonder if this output can be incorporated into the source documentation wiki at wiki.blender.org. That would be quite poawerful if it could automatically update with changes to comments and in code documentation.
I have done such things and was planning to introduce that as soon as needed structure is in place. 
How?
Well that depends, as they say.
Is this a mockup, or have you really made this? I’d love to have a link.
Mocup? Oh…
No, just me making my own Doxyfile and some changes.
The layout and visual style can be controlled quite easily.
I will submit the changes as soon as I get some up-votes on the task I added.
(Hope I didn’t do something I shouldn’t)
Some comments attending @dfelinto’s Tracker Curfew post resonate here:
Currently the core Blender developers are drowning in work. Giving them more work doesn’t solve that situation. Sybren A. Stüvel
Dr. Stüvel reports that the core development team is 100% tapped. Ditto the few dozen volunteer coders ringing the core. They won’t write documentation. Maybe they want to, but apart from design tasks they can’t. They’re tapped.
To my mind, the only resources available for documentation comes from something like Mr. Dade’s pipeline. The wiki documents something like it: New Developer Introduction. I believe a useful addition to the Tasks for new developers page would be a module documentation task.
The deliverable would be code level documentation packaged in a Blender standard, Doxygen-compatible template suitable for inclusion in Blender sources. This library of Blender standard, Doxygen friendly, templates doesn’t exist as far as I know; they may as well be of your design, the deliverables that favorably resolves T73140.
It seems to me that the delivery mechanism of such module patches fits right in with the delivery of any other code patch. Module authors start here and create a differential. Perhaps some additional guidelines could be put on that page - specifically for module template authors - concerning concise language and word-count limits. Apart from that, authors create a git diff and go through the same delivery steps as any other patch author, including appointing reviewers. Reviewers check for accuracy and subtract brownie points for overly-wordy or too-sparse contributions.
I, for one, would be willing to contribute to Blender through such a conduit. I would find it very convenient to grab a Doxygen-friendly template that someone else has worked out, freeing me up for word craft. Thank you for stepping up to the plate on this.
Changes to the landing page raise quite a few questions about where this page fits, this isn’t clear since the documents are currently not published on blender.org.
So, if you like to work on this and there is general agreement among developers that your changes are an improvement, its fine… however there is a real risk you wont get enough useful feedback.
Again, suggest improve the docs on a single module. This has the advantage that only the module owners needs to review it.
Thank-you, @grosgood, for your feedback!
I am currently working through a more concrete example covering only a few
parts of the Doxygen configuration and structure, just as @ideasman42 requested.
There will be an improved Doxyfile with style and layout hooks in place and small but
concrete examples for how to give the content a nav-friendly structure with minimal effort.
The main issue for me just now is that the @ingroup tag has been hijacked to group files when it’s actually the only relevant mechanism by which to group functionality spread over several files. This breaks all good usage-patterns that I know.
But don’t worry, I know how to introduce some clarifying changes in small increments.
I am grateful that the team is patient while I figure out who I’m talking to. I always try
to adapt my messages to the receiver when I work with these things. Quite naturally
this is quite different in this setting so…
I’m thinking that the first contribution may add the option to compare the new and the old by splitting Doxyfile into blender_orig.dox and blender.dox. That way you can choose by calling doxygen blender_orig.dox when you want to see the original content for reference and so on.
Cheers!
Hi @ideasman42 !
Do you have any suggestion about which modules there’s a chance to get at least a little feedbcak?
There are a handful I’d recommend, that are small enough not to be overwhelming, but big enough to be useful for developers.
BLF_*.h (blendfont library), font API’s are used for the UI, for rendering text overlays, the text editor, it’s Python API & displaying translated strings (this is my first choice).
Developers run into this library often enough, we might benefit from improvements here. Also the library isn’t huge.
IMB_*.h (image buffer API), this has more historic code than BLF and is due for a refactor, nevertheless, it’s a fairly isolated image API which might also benefit from improved docs.
BLI_math_*.h while this is part of BLI, the math part could use some special attention since it’s used a lot and any confusion here leads to bugs.
creator*.c while this isn’t a library, it’s the entry point for Blender’s main, handing setup and argument parsing. An improved overview could help.
…other devs may suggest different areas, but think these are all reasonable places to start.
