README.md: Fix 'Related Tools' heading...
eldoc-sh-doxygen.el: Set version string to 0.1.0
README.md: Re-generate
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.
@param
at minimum), this package does nothing.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...]
}
Only the @param
keywords are currently recognized/required by this package.
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)).
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)
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)
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).
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! ;)
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.