Skip to content

Commit 2dea745

Browse files
zonuexezonuexe
committed
Impl New MlDoc
 * Change term "spec" to "form" * Change term "args" to "params" * Change naming rules (mldoc-foo-* to foo-mldoc-*) * Modify construct of mldoc-list * Move :function into :values plist * Fixed some errors
1 parent e556fe3 commit 2dea745

File tree

3 files changed

+77
-76
lines changed

3 files changed

+77
-76
lines changed

‎README.org‎

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ MLDoc has APIs for end users and Lisp package developers.
1414
(defun my-foo-mode-setup ()
1515
"Setup function for `foo-mode'."
1616
(mldoc-mode 1)
17-
(setq mldoc-documentation-functions '(mldoc-foo mldoc-html)))
17+
(push mldoc-documentation-functions #'mldoc-foo)
18+
(push mldoc-documentation-functions #'mldoc-html))
1819

1920
(with-eval-after-load "foo-mode"
2021
(add-hook 'foo-mode-hook 'my-foo-mode-setup))
@@ -23,37 +24,38 @@ MLDoc has APIs for end users and Lisp package developers.
2324
*** MLDoc DSL
2425
**** Example
2526
#+BEGIN_SRC emacs-lisp
26-
(defcustom mldoc-foo-function-spec
27-
'(return-type " " function "(" (args ", " :type " " :name) ")")
28-
"MLDoc display spec for Foo function call."
27+
(defcustom foo-mldoc-function-form
28+
'(return-type " " function "(" (params ", " :type " " :name) ")")
29+
"MLDoc display format for Foo function call."
2930
:group 'mldoc-foo
3031
:type 'sexp)
3132

32-
(define-mldoc mldoc-foo
33+
(define-mldoc foo-mldoc-func
3334
"MLDoc function for Foo language."
3435
;; This function is extremely simplified, but represents the specification of
3536
;; the value that an actual implementation should return.
36-
(mldoc-list mldoc-foo-function-spec :function "print"
37-
:args '((:type "string" :name "message"))
38-
:current-arg 0))
37+
(mldoc-list foo-mldoc-function-form
38+
:params '((:type "string" :name "message"))
39+
:current-param 0
40+
:values (list :function "print")))
3941
#+END_SRC
4042
**** Format
41-
Actually the DSL is just a list. Its structure is =(cons spec plist)=.
42-
***** spec
43-
*spec* is a notation for converting a list to a string.
44-
- ="string"=: Just combined with that value.
43+
Actually the DSL is just a list. Its structure is =(cons form plist)=.
44+
***** form
45+
*form* is a notation for converting a list to a string.
46+
- =\"string\"=: Just combined with that value.
4547
- =:keyword=: The value passed as a keyword in =plist=.
4648
- =symbol=: Symbol is evaluated as a variable name.
47-
- =(args separator &optional argspec)=: This looks like a function, but combines =:args= with =separator=.
49+
- =(params separator &optional param-info)=: This looks like a function, but combines =:params= with =separator=.
4850
- *separator*: In languages similar to C, =", "= is assumed.
49-
- *argspec*: spec for arguments.
51+
- *paraminfo*: A plist for parameters.
5052
- =(eval ...)=: The expression following =eval= is evaluated as Emacs Lisp.
51-
- =(if cond then ...else)=, =(when cond ...body)==, =(unless cond ...body)=: Same as Emacs Lisp.
53+
- =(if cond then ...else)=, =(when cond ...body)=, =(unless cond ...body)=: Same as Emacs Lisp.
5254
- Any other list is evaluated as a Emacs Lisp expression.
5355
***** plist
5456
It is an [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Property-Lists.html#Property-Lists][Property List]] with the following keys.
55-
- =:args=: List of =string= or =plist=.
56-
- =:current-arg=: 0-origin current position of argument list.
57+
- =:params=: List of =string= or =plist=.
58+
- =:current-param=: 0-origin current position of argument list.
5759
*** macro =(define-mldoc name docstring &rest body)=
5860
This macro is very similar to defun.
5961
It's actually just a defun wrapper, but it is responsible for converting between MLDoc DSL and ElDoc output formats.

‎mldoc.el‎

Lines changed: 45 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646

4747
(defvar mldoc-default-eldoc-propertizers
4848
'((:function . ((face . font-lock-function-name-face)))
49+
(:constant . ((face . font-lock-constant-face)))
4950
(:return-type . ((face . font-lock-type-face)))
5051
(:type . ((face . font-lock-type-face)))
5152
(:warning . ((face . font-lock-warning-face))))
@@ -62,7 +63,7 @@
6263
(defvar-local mldoc-propertizer* nil
6364
"Dynamic bound list of propertizers.")
6465

65-
;; Utility functions
66+
;; Utility functions for users
6667
(defsubst mldoc-in-string ()
6768
"Return non-nil if inside a string.
6869
it is the character that will terminate the string, or t if the string should be terminated by a generic string delimiter."
@@ -88,32 +89,34 @@ The definition is (lambda ARGLIST [DOCSTRING] BODY...)."
8889
(mapconcat #'identity (apply #'mldoc--build-list doc) "")
8990
doc))))
9091

91-
(defun mldoc--propertize-arg (arg is-current-arg arg-spec)
92-
"Propertize ARG by IS-CURRENT-ARG and ARG-SPEC."
93-
(cl-loop
94-
for spec in arg-spec
95-
collect
96-
(if (stringp spec)
97-
spec
98-
(let ((v (plist-get arg spec)))
99-
(if (null v)
100-
""
101-
(if (and is-current-arg (eq :name spec))
102-
(propertize v 'face '(:weight bold))
103-
(mldoc--propertize-keyword arg spec)))))))
104-
105-
(defun mldoc--propertize-args (args current-arg arg-separator &optional arg-spec)
106-
"Return propertized string by ARGS list, CURRENT-ARG, ARG-SEPARATOR and ARG-SPEC."
92+
(defun mldoc--propertize-param (param is-current-param doc-form)
93+
"Propertize PARAM by IS-CURRENT-PARAM and DOC-FORM."
10794
(mapconcat
108-
#'append
109-
(cl-loop for arg in args
110-
for n = 0 then (1+ n)
111-
append
112-
(mldoc--propertize-arg
113-
(if (stringp arg) (list :name arg) arg)
114-
(eq current-arg n)
115-
(or arg-spec (list :name))))
116-
(or arg-separator ", ")))
95+
(lambda (spec)
96+
(if (stringp spec)
97+
spec
98+
(let ((v (plist-get param spec)))
99+
(if (null v)
100+
""
101+
(if (and is-current-param (eq :name spec))
102+
(propertize v 'face '(:weight bold))
103+
(mldoc--propertize-keyword param spec))))))
104+
doc-form
105+
""))
106+
107+
(defun mldoc--propertize-params (params current-param param-separator &optional doc-form)
108+
"Return propertized string by PARAMS list, CURRENT-PARAM, PARAM-SEPARATOR and DOC-FORM."
109+
(let ((n 0))
110+
(mapconcat
111+
(lambda (param)
112+
(prog1
113+
(mldoc--propertize-param
114+
(if (stringp param) (list :name param) param)
115+
(eq current-param n)
116+
(or doc-form (list :name)))
117+
(setq n (1+ n))))
118+
params
119+
(or param-separator ", "))))
117120

118121
(defun mldoc--propertizers-to-list (propertizer)
119122
"Return list for function `propertize' by PROPERTIZER alist."
@@ -127,47 +130,44 @@ The definition is (lambda ARGLIST [DOCSTRING] BODY...)."
127130
(funcall val)
128131
val))
129132
(prop (cdr-safe (assq key mldoc-propertizer*))))
130-
(if (null prop)
133+
(if (not (and prop str))
131134
(or str "")
132135
(apply #'propertize str (mldoc--propertizers-to-list prop)))))
133136

134-
(cl-defmacro mldoc-list (spec &key function propertizers args current-arg values)
137+
(cl-defmacro mldoc-list (form &key propertizers params current-param values)
135138
"Build a list acceptable by MLDoc."
136-
`(list ,spec
137-
:function ,function
139+
`(list ,form
138140
:propertizers ,propertizers
139-
:args ,args
140-
:current-arg ,current-arg
141+
:params ,params
142+
:current-param ,current-param
141143
:values ,values))
142144

143-
(cl-defun mldoc--build-list (spec &key function propertizers args current-arg values)
145+
(cl-defun mldoc--build-list (spec &key propertizers params current-param values)
144146
"Return a list of propertized string for ElDoc.
145147
146-
integer `:current-arg'
148+
integer `:current-param'
147149
0-origin offset to current position of arguments.
148150
plist `values'
149151
Property list of (:name value)
150152
"
151-
(setq values (plist-put values :function function))
152-
(setq values (plist-put values :args args))
153+
(setq values (plist-put values :params params))
153154
(let ((mldoc-propertizer*
154155
(append propertizers mldoc-default-eldoc-propertizers)))
155156
(cl-loop
156157
for s in spec collect
157158
(cond
159+
((null s) nil)
158160
((stringp s) s)
159-
((symbolp s)
160-
(if (not (keywordp s))
161-
(symbol-value s)
162-
(mldoc--propertize-keyword values s)))
163-
((listp s) (mldoc--evalute-spec s args current-arg))))))
164-
165-
(defun mldoc--evalute-spec (spec args current-arg)
166-
"Evalute ARGS and embedded element of SPEC."
161+
((keywordp s) (mldoc--propertize-keyword values s))
162+
((symbolp s) (symbol-value s))
163+
((listp s) (mldoc--evalute-spec s params current-param))))))
164+
165+
(defun mldoc--evalute-spec (spec params current-param)
166+
"Evalute PARAMS and embedded element of SPEC."
167167
(let ((f (car spec))
168168
(rest (cdr spec)))
169169
(cl-case f
170-
(args (mldoc--propertize-args args current-arg (car rest) (cdr rest)))
170+
(params (mldoc--propertize-params params current-param (car rest) (cdr rest)))
171171
(if (if (eval (car rest)) (eval (nth 1 rest)) (eval (cons 'progn (cddr rest)))))
172172
(when (when (eval (car rest)) (eval (cons 'progn (cdr rest)))))
173173
(unless (unless (eval (car rest)) (eval (cons 'progn (cdr rest)))))

‎tests/mldoc-test.el‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -38,14 +38,14 @@
3838
,(list ""))
3939
("Spec has function value"
4040
,(mldoc--build-list '(:foo ": " :function)
41-
:function "f" :values (list :foo "hoge"))
41+
:values (list :function "f" :foo "hoge"))
4242
,(list "hoge" ": "
4343
(propertize "f" 'face font-lock-function-name-face)))
4444
("Spec has arg list"
45-
,(mldoc--build-list '(:function "(" (args ", ") ")")
46-
:function "f"
47-
:args '("a" "b" "c")
48-
:current-arg 2)
45+
,(mldoc--build-list '(:function "(" (params ", ") ")")
46+
:values (list :function "f")
47+
:params '("a" "b" "c")
48+
:current-param 2)
4949
,(list (propertize "f" 'face font-lock-function-name-face)
5050
"("
5151
(concat "a, " (propertize "b" 'face '(:weight bold)) ", c")
@@ -54,21 +54,20 @@
5454
(cl-loop for (desc actual expected) in data
5555
do (should (equal (cons desc expected) (cons desc actual))))))
5656

57-
(ert-deftest mldoc-test--propertize-arg ()
57+
(ert-deftest mldoc-test--propertize-param ()
5858
(let ((data
59-
;; (mldoc--propertize-arg arg is-current-arg arg-spec)
59+
;; (mldoc--propertize-arg arg is-current-param arg-spec)
6060
`(("Simple argument"
61-
,(mldoc--propertize-arg '(:name "a") nil '(:name))
62-
,(list "a"))
61+
,(mldoc--propertize-param '(:name "a") nil '(:name))
62+
"a")
6363
("Simple argument and current argument"
64-
,(mldoc--propertize-arg '(:name "a") t '(:name))
65-
,(list (propertize "a" 'face '(:weight bold))))
64+
,(mldoc--propertize-param '(:name "a") t '(:name))
65+
,(propertize "a" 'face '(:weight bold)))
6666
("Argument has :name and :type"
67-
,(mldoc--propertize-arg '(:name "a" :type "string")
67+
,(mldoc--propertize-param '(:name "a" :type "string")
6868
nil
6969
'(:name " / " :type))
70-
,(list "a" " / "
71-
(propertize "string" 'face font-lock-function-name-face))))))
70+
,(concat "a / " (propertize "string" 'face font-lock-function-name-face))))))
7271
(cl-loop for (desc actual expected) in data
7372
do (should (equal (cons desc expected) (cons desc actual))))))
7473

0 commit comments

Comments
 (0)