emacs-php / muldoc

Multi ElDoc integration

MulDoc - Multi ElDoc integration

MulDoc extends ElDoc and makes function definition very easy.

What is ElDoc?

ElDoc is a minor mode to show documentation in echo area. ElDoc function is implemented for several languages besides Emacs Lisp.

Why MulDoc?

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.

API for users

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))

API for developers

MulDoc DSL

Example

(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")))

Format

Actually the DSL is just a list. Its structure is (cons form plist).

form

form is a notation for converting a list to a string.

• ="string"=: Just combined with that value.
• :keyword: The value passed as a keyword in plist.
• symbol: Symbol is evaluated as a variable name.
• (params separator &optional param-info): This looks like a function, but combines :params with separator.
  • separator: In languages similar to C, =”, “= is assumed.
  • paraminfo: A plist for parameters.
• (eval ...): The expression following eval 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.

plist

It is an Property List with the following keys.

• :params: List of string or plist.
• :current-param: 0-origin current position of argument list.

macro (define-muldoc name docstring &rest body)

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.