158 |
;; Return the text we displayed. |
;; Return the text we displayed. |
159 |
(buffer-string)))))) |
(buffer-string)))))) |
160 |
|
|
161 |
(defun help-split-fundoc (doc def) |
(defun help-split-fundoc (docstring def) |
162 |
"Split a function docstring DOC into the actual doc and the usage info. |
"Split a function DOCSTRING into the actual doc and the usage info. |
163 |
Return (USAGE . DOC) or nil if there's no usage info. |
Return (USAGE . DOC) or nil if there's no usage info. |
164 |
DEF is the function whose usage we're looking for in DOC." |
DEF is the function whose usage we're looking for in DOCSTRING." |
165 |
;; Functions can get the calling sequence at the end of the doc string. |
;; Functions can get the calling sequence at the end of the doc string. |
166 |
;; In cases where `function' has been fset to a subr we can't search for |
;; In cases where `function' has been fset to a subr we can't search for |
167 |
;; function's name in the doc string so we use `fn' as the anonymous |
;; function's name in the doc string so we use `fn' as the anonymous |
168 |
;; function name instead. |
;; function name instead. |
169 |
(when (and doc (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" doc)) |
(when (and docstring (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring)) |
170 |
(cons (format "(%s%s" |
(cons (format "(%s%s" |
171 |
;; Replace `fn' with the actual function name. |
;; Replace `fn' with the actual function name. |
172 |
(if (consp def) "anonymous" def) |
(if (consp def) "anonymous" def) |
173 |
(match-string 1 doc)) |
(match-string 1 docstring)) |
174 |
(substring doc 0 (match-beginning 0))))) |
(substring docstring 0 (match-beginning 0))))) |
175 |
|
|
176 |
(defun help-add-fundoc-usage (doc arglist) |
(defun help-add-fundoc-usage (docstring arglist) |
177 |
"Add the usage info to the docstring DOC. |
"Add the usage info to DOCSTRING. |
178 |
If DOC already has a usage info, then just return DOC unchanged. |
If DOCSTRING already has a usage info, then just return it unchanged. |
179 |
The usage info is built from ARGLIST. DOC can be nil. |
The usage info is built from ARGLIST. DOCSTRING can be nil. |
180 |
ARGLIST can also be t or a string of the form \"(fun ARG1 ARG2 ...)\"." |
ARGLIST can also be t or a string of the form \"(FUN ARG1 ARG2 ...)\"." |
181 |
(unless (stringp doc) (setq doc "Not documented")) |
(unless (stringp docstring) (setq docstring "Not documented")) |
182 |
(if (or (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" doc) (eq arglist t)) |
(if (or (string-match "\n\n(fn\\(\\( .*\\)?)\\)\\'" docstring) (eq arglist t)) |
183 |
doc |
docstring |
184 |
(format "%s%s%S" doc |
(format "%s%s%S" docstring |
185 |
(if (string-match "\n?\n\\'" doc) |
(if (string-match "\n?\n\\'" docstring) |
186 |
(if (< (- (match-end 0) (match-beginning 0)) 2) "\n" "") |
(if (< (- (match-end 0) (match-beginning 0)) 2) "\n" "") |
187 |
"\n\n") |
"\n\n") |
188 |
(if (and (stringp arglist) |
(if (and (stringp arglist) |
239 |
(concat "src/" file) |
(concat "src/" file) |
240 |
file))))) |
file))))) |
241 |
|
|
242 |
(defface help-argument-name '((t (:slant italic))) |
(defun help-default-arg-highlight (arg) |
243 |
"Face to highlight function arguments in docstrings.") |
"Default function to highlight arguments in *Help* buffers. |
244 |
|
It returns ARG in lowercase italics, if the display supports it; |
245 |
|
else ARG is returned in uppercase normal." |
246 |
|
(let ((attrs '(:slant italic))) |
247 |
|
(if (display-supports-face-attributes-p attrs) |
248 |
|
(propertize (downcase arg) 'face attrs) |
249 |
|
arg))) |
250 |
|
|
251 |
(defun help-do-arg-highlight (doc args) |
(defun help-do-arg-highlight (doc args) |
252 |
(with-syntax-table (make-syntax-table emacs-lisp-mode-syntax-table) |
(with-syntax-table (make-syntax-table emacs-lisp-mode-syntax-table) |
254 |
(while args |
(while args |
255 |
(let ((arg (prog1 (car args) (setq args (cdr args))))) |
(let ((arg (prog1 (car args) (setq args (cdr args))))) |
256 |
(setq doc (replace-regexp-in-string |
(setq doc (replace-regexp-in-string |
257 |
(concat "\\<\\(" arg "\\)\\(?:es\\|s\\|th\\)?\\>") |
;; This is heuristic, but covers all common cases |
258 |
(propertize arg 'face 'help-argument-name) |
;; except ARG1-ARG2 |
259 |
|
(concat "\\<" ; beginning of word |
260 |
|
"\\(?:[a-z-]+-\\)?" ; for xxx-ARG |
261 |
|
"\\(" |
262 |
|
arg |
263 |
|
"\\)" |
264 |
|
"\\(?:es\\|s\\|th\\)?" ; for ARGth, ARGs |
265 |
|
"\\(?:-[a-z-]+\\)?" ; for ARG-xxx |
266 |
|
"\\>") ; end of word |
267 |
|
(help-default-arg-highlight arg) |
268 |
doc t t 1)))) |
doc t t 1)))) |
269 |
doc)) |
doc)) |
270 |
|
|