~trs-80/eldoc-sh-doxygen

eldoc-sh-doxygen

#eldoc-sh-doxygen

#Introduction

Emacs ElDoc support for sh-mode (editing shell scripts).

ElDoc is the thing where, with point on a function, you get some text in the message area with the function name and it's argument list. Which is different from completion.

One particularly nice feature of this package, is that it recursively searches through any additional source'd files in order to find all functions which should be callable from the current file.

Since shell languages are not really self-documenting in the same way that Emacs (Lisp) is, we need to provide some sort of structured data to parse. I chose Doxygen for this as it's already widely supported in other languages and has a lot of already existing tools and options.

N.B.: Without adding the Doxygen style comment tags mentioned in the next section (@param at minimum), this package does nothing.

#Doxygen comments

In order for any of this to work, you MUST comment your functions using Doxygen notation/tags, for example:

## @fn debian_package_insure ()
## @brief Insure Debian package is installed (if not, then install it).
## @param Package The package name you want to check for / install.  Required.
## @param Release The Debian target release (e.g., stable, buster-backports,
## etc.).  Optional.
debian_package_insure () {

    local Package="$1"
    local Release="$2"

    # Issue a message
    echo "Checking status of Debian package $Package..."

    # [rest of function...]
}

A few important notes about the above:
- Only the @param keywords are currently recognized/required by this package.
  - Although while you are at it, you may want to add the rest if you want to automatically generate nice looking HTML (and man pages, and other sorts of docs). See Doxygen itself for more about that.
- The blank line above the comment block is required for this package.
- The double comment symbol (##) is also required by this package (and also by bash-doxygen if you use that (see Related Tools)).

#Installation

Easiest way (considering updates) is just to clone this repo for the time being:

~/ $ cd git/ext
~/git/ext $ git clone https://git.sr.ht/~trs-80/eldoc-sh-doxygen

Add something like the following to your init file:

(add-to-list 'load-path "~/git/ext/eldoc-sh-doxygen")
(require 'eldoc-sh-doxygen)

#Setup / Starting

Do one of the following, either:

To run once manually while in an sh-mode buffer, press M-: and evaluate the following snippet:

(add-function :before-until (local 'eldoc-documentation-function)
          #'sh-eldoc-documentation-function)

Or, if you want it to run every time sh-mode is started, put the same snippet to a custom function which we will in turn insert to the variable sh-mode-hook, like so:

(defun my-sh-mode-setup ()
  "Personalized customization for `sh-mode'."
  (add-function :before-until (local 'eldoc-documentation-function)
        #'sh-eldoc-documentation-function))

(add-hook sh-mode-hook #'my-sh-mode-setup)

#Roadmap

There are a few things I do have some ideas – but not time, currently – about working on:

Maybe sooner:
- [ ] Make the current argument you are typing show up in bold (like it does in Emacs Lisp mode for instance).
- [ ] Improve regexp to include any characters which are legal in a shell function name (currently only [A-Za-z_] are recognized which is quite naive).
- [ ] Improve regexp(s) to account for the keyword function coming before a function name (currently we simply search for the function name followed by a space and then () which is quite naive).
Maybe later (if ever):
- [ ] The function elisp-get-fnsym-args-string (which is the Emacs Lisp equivalent, and model I based my eldoc-sh-get-function-args-string function upon) will return a brief description in lieu of an argument list if it can't find the latter. Perhaps implement some similar functionality.
- [ ] Refactor what I consider to be some hacky code in places (although so far everything seems to work).
  - Search for keyword HACK in comments to find some of these if you are interested (other keywords used are NOTE, REVIEW, TODO, etc.).
- [ ] Maybe implement importing tags from Doxygen (which as I understand can generate them) as an alternative to searching through buffers with regexps to gather the function arguments.
Other
- If you are really having some problem, please do create an issue in the tracker here. I don't have a lot of time these days, but I'll do what I can to help.
- Last but certainly not least, patches welcome of course! ;)

#Release History

2021-10-12 - v0.1.0
- I just barely got this initally working and quickly wrote a README and packaged it up for quick release. It "works for me" but I currently consider it alpha software. See also Roadmap.

bash-doxygen - A basic doxygen filter (originally written in GNU sed) allowing you to add inline-documentation to your bash shell scripts.
- You will actually need this in addition to Doxygen itself in order for Doxygen to be able to generate all the nice docs automatically.
- But it is not required at all for this package to work in Emacs.

refs

clone