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:
- Find material to mimic and reference regarding this.
- Get feedback, like yours, so I understand the current mindset.
- Provoke a discussion about approaches.
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.