Hello David,
Having a standardised format is what makes this so useful. The whole point of this is to make sure that everybody uses the same convention so third-party tools can integrate with the system. If everybody “adopts the convention they prefer”, as you suggest, such a system would not be very useful. With regards to the format, I think you are exaggerating the complexity a bit. It's really only two rules:
- The documentation block is prefixed by ⍝⍝
- The first line is the short summary.
Using a special format to describe documentation is very important. The reason is that you absolutely don't want to display “normal” comments as documentation. Using ⍝⍝ tells the system that the person who wrote the documentation intended this to be documentation, and not just merely a plain comment.
The Emacs mode dynamically pops up this documentation string whenever the cursor is on top of a function name, and you really don't want arbitrary comments to be displayed there.
This system of having dedicated documentation strings is very well established in multiple languages, for example:
- Java (uses /**)
- C++ (doxygen, uses /**)
- Python (uses triple-quote """like this""". An empty string conveniently is a no-op in Python)
- Common Lisp ("a plain string" as the first form, like Python this ends up being a no-op)
- Emacs Lisp (same syntax as Common Lisp, the documentation is tightly integrated in the help system)
As you can see, this is nothing new, and has proven to be incredibly useful in multiple languages.
Finally, this is not merely a good idea. It's also actively working in the GNU APL Emacs mode today, and if you want to have integrated documentation in the editor you need to follow this convention anyway.
Regards,
Elias