MulDoc extends ElDoc and makes function definition very easy.
ElDoc is a minor mode to show documentation in echo area. ElDoc function is implemented for several languages besides Emacs Lisp.
MulDoc solves ElDoc problem.
- ElDoc can usually only register one or two functions.
- ElDoc implementations are difficult to understand and tends to be untestable.
MulDoc has APIs for end users and Lisp package developers.
Note: no end-user MulDoc implementation yet.
(defun my-foo-mode-setup ()
"Setup function for `foo-mode'."
(muldoc-mode 1)
(push muldoc-documentation-functions #'muldoc-foo)
(push muldoc-documentation-functions #'muldoc-html))
(with-eval-after-load "foo-mode"
(add-hook 'foo-mode-hook 'my-foo-mode-setup))
(defcustom foo-muldoc-function-form
'(return-type " " function "(" (params ", " :type " " :name) ")")
"MulDoc display format for Foo function call."
:group 'muldoc-foo
:type 'sexp)
(define-muldoc foo-muldoc-func
"MulDoc function for Foo language."
;; This function is extremely simplified, but represents the specification of
;; the value that an actual implementation should return.
(muldoc-list foo-muldoc-function-form
:params '((:type "string" :name "message"))
:current-param 0
:values (list :function "print")))
Actually the DSL is just a list. Its structure is (cons form plist)
.
form is a notation for converting a list to a string.
\"string\"
: Just combined with that value.:keyword
: The value passed as a keyword inplist
.symbol
: Symbol is evaluated as a variable name.(params separator &optional param-info)
: This looks like a function, but combines:params
withseparator
.- separator: In languages similar to C,
", "
is assumed. - paraminfo: A plist for parameters.
- separator: In languages similar to C,
(eval ...)
: The expression followingeval
is evaluated as Emacs Lisp.(if cond then ...else)
,(when cond ...body)
,(unless cond ...body)
: Same as Emacs Lisp.- Any other list is evaluated as a Emacs Lisp expression.
It is an Property List with the following keys.
:params
: List ofstring
orplist
.:current-param
: 0-origin current position of argument list.
This macro is very similar to defun. It’s actually just a defun wrapper, but it is responsible for converting between MulDoc DSL and ElDoc output formats.