Generated API documentation for bash-completion

[titaniumtraveler]

Considering that the functions in ./bash_completion are all annotated and documented, would it be a good idea to generate a more human readable API documentation from that?

(Or maybe that already exists and I have not noticed it)

[akinomyoga]

I also think about it recently (in relation to #1328). FYI, we once discussed it in #746. We currently don't have a processor to convert them. @scop's reply then was this:

#746 (comment)

I'm not aware of a processor nor a specific set of keywords to use with the @ prefixed markers. They were introduced by someone else a long time ago. They do look a lot like Java/PHP comments.

To me, the most important thing regarding these comment blocks would be to show a "quick help" in editors/IDE's with the info from the comments when hovering over a function, either just as-is, or if there's some structure supported, even better. Personally for shell code I'm using mostly Emacs, and JetBrains IDEs every now and then, and ad hoc vim edits at times, but I'm not aware of a comment/doc format for shell code that would work with any of these (haven't even really looked TBH though). In addition to that, I wouldn't mind a processor that can be run separately to produce e.g. HTML docs, but quite frankly that's not at all that interesting to me.

[akinomyoga]

I also use similar code documentation in my project. If we create a processor for the code documentation, we might share it among multiple shell projects. There has been also an inquiry about the documentation generator in my project: akinomyoga/ble.sh#351.

[titaniumtraveler]

Interesting, I might look into this further, because if there were something to generate machine readable information from the annotations, it might be possible to at least hack something together with efm-language-server.