Best practices for Mendix Development, section 4.2.2 Documentation and Annotations states:
"All complex microflows (more than ten activities or more than two splits) must have an annotation describing the purpose of the microflow and expected parameters and return values. This annotation must be placed at the start, so it is visible when the microflow is opened. This will assist other developers in quickly understanding the general purpose of a microflow, without having to read through it entirely."
As annotations are not included when using the 'export documentation... feature', this would require me to maintain the documentation in two different locations (the annotation and the microflow documentation). Which doesn't make a lot of sense to me.
So either this is best practice isn't so good after all. Or it implies the implementation of the documentation feature isn't helping us developers a lot (as it is overlooked in the microflow's properties window) and should better be removed as a feature.
Either way, maybe it would be better to have documentation on the start and/or end events. That will become visible in the modeller window on hover and which also will be used when generating the project documentation.
Or any annotations associated with the start and/or end events will also be included in the (generated) project documentation.
First I would not necessarily try to apply a (java) coding pattern to a low-code platform as Mendix.
Second, don't pull such a statement out of its context. The first statement applies explicitly to inline comments.
I fully agree though, that you should not take this 'Mendix best practice' as is.
However, the initial problem here is one I also found confusing - The microflow documentation and some annotation beeing treated as documentation should be in sync. Otherwise the documentation feature and annotation best practice just don't fit together. The best I could think of would be to place a 'Documentation annotation' that you can mark as documentation and that will be exported.
The Software Improvement Group on comments (from Building Maintainable Software, by Joost Visser, Chapter 11: Write Clean Code): "Comments are sometimes considered the anti-pattern of good code. From our experience we can confirm that inline comments typically indicate a lack of elegant engineering solutions." This section ends with "In general, the best advice we can give is to keep your code free of comments."
I'm not saying you should treat the SIG as an authority, but be aware that there are very different opinions on comments, which both annotations and documentation feature are.