104421
|
1 ;;; doc.el --- Routines for documentation strings
|
|
2
|
|
3 ;;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2005, 2008, 2009
|
|
4 ;;; Free Software Foundation, Inc.
|
|
5
|
|
6 ;; Author: Eric M. Ludlam <zappo@gnu.org>
|
|
7 ;; Keywords: syntax
|
|
8
|
|
9 ;; This file is part of GNU Emacs.
|
|
10
|
|
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
|
|
12 ;; it under the terms of the GNU General Public License as published by
|
|
13 ;; the Free Software Foundation, either version 3 of the License, or
|
|
14 ;; (at your option) any later version.
|
|
15
|
|
16 ;; GNU Emacs is distributed in the hope that it will be useful,
|
|
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
19 ;; GNU General Public License for more details.
|
|
20
|
|
21 ;; You should have received a copy of the GNU General Public License
|
|
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
|
|
23
|
|
24 ;;; Commentary:
|
|
25 ;;
|
|
26 ;; It is good practice to write documenation for your functions and
|
|
27 ;; variables. These core routines deal with these documentation
|
|
28 ;; comments or strings. They can exist either as a tag property
|
|
29 ;; (:documentation) or as a comment just before the symbol, or after
|
|
30 ;; the symbol on the same line.
|
|
31
|
|
32 (require 'semantic/tag)
|
|
33
|
|
34 ;;; Code:
|
|
35
|
|
36 (define-overloadable-function semantic-documentation-for-tag (&optional tag nosnarf)
|
|
37 "Find documentation from TAG and return it as a clean string.
|
|
38 TAG might have DOCUMENTATION set in it already. If not, there may be
|
|
39 some documentation in a comment preceding TAG's definition which we
|
|
40 can look for. When appropriate, this can be overridden by a language specific
|
|
41 enhancement.
|
|
42 Optional argument NOSNARF means to only return the lexical analyzer token for it.
|
|
43 If nosnarf if 'lex, then only return the lex token."
|
|
44 (if (not tag) (setq tag (semantic-current-tag)))
|
|
45 (save-excursion
|
|
46 (when (semantic-tag-with-position-p tag)
|
|
47 (set-buffer (semantic-tag-buffer tag)))
|
|
48 (:override
|
|
49 ;; No override. Try something simple to find documentation nearby
|
|
50 (save-excursion
|
|
51 (semantic-go-to-tag tag)
|
|
52 (let ((doctmp (semantic-tag-docstring tag (current-buffer))))
|
|
53 (or
|
|
54 ;; Is there doc in the tag???
|
|
55 doctmp
|
|
56 ;; Check just before the definition.
|
|
57 (when (semantic-tag-with-position-p tag)
|
|
58 (semantic-documentation-comment-preceeding-tag tag nosnarf))
|
|
59 ;; Lets look for comments either after the definition, but before code:
|
|
60 ;; Not sure yet. Fill in something clever later....
|
|
61 nil))))))
|
|
62
|
|
63 (defun semantic-documentation-comment-preceeding-tag (&optional tag nosnarf)
|
|
64 "Find a comment preceeding TAG.
|
|
65 If TAG is nil. use the tag under point.
|
|
66 Searches the space between TAG and the preceeding tag for a comment,
|
|
67 and converts the comment into clean documentation.
|
|
68 Optional argument NOSNARF with a value of 'lex means to return
|
|
69 just the lexical token and not the string."
|
|
70 (if (not tag) (setq tag (semantic-current-tag)))
|
|
71 (save-excursion
|
|
72 ;; Find this tag.
|
|
73 (semantic-go-to-tag tag)
|
|
74 (let* ((starttag (semantic-find-tag-by-overlay-prev
|
|
75 (semantic-tag-start tag)))
|
|
76 (start (if starttag
|
|
77 (semantic-tag-end starttag)
|
|
78 (point-min))))
|
|
79 (when (re-search-backward comment-start-skip start t)
|
|
80 ;; We found a comment that doesn't belong to the body
|
|
81 ;; of a function.
|
|
82 (semantic-doc-snarf-comment-for-tag nosnarf)))
|
|
83 ))
|
|
84
|
|
85 (make-obsolete-overload 'semantic-find-documentation
|
|
86 'semantic-documentation-for-tag)
|
|
87
|
|
88 (defun semantic-doc-snarf-comment-for-tag (nosnarf)
|
|
89 "Snarf up the comment at POINT for `semantic-documentation-for-tag'.
|
|
90 Attempt to strip out comment syntactic sugar.
|
|
91 Argument NOSNARF means don't modify the found text.
|
|
92 If NOSNARF is 'lex, then return the lex token."
|
|
93 (let* ((semantic-ignore-comments nil)
|
|
94 (semantic-lex-analyzer #'semantic-comment-lexer))
|
|
95 (if (memq nosnarf '(lex flex)) ;; keep `flex' for compatibility
|
|
96 (car (semantic-lex (point) (1+ (point))))
|
|
97 (let ((ct (semantic-lex-token-text
|
|
98 (car (semantic-lex (point) (1+ (point)))))))
|
|
99 (if nosnarf
|
|
100 nil
|
|
101 ;; ok, try to clean the text up.
|
|
102 ;; Comment start thingy
|
|
103 (while (string-match (concat "^\\s-*" comment-start-skip) ct)
|
|
104 (setq ct (concat (substring ct 0 (match-beginning 0))
|
|
105 (substring ct (match-end 0)))))
|
|
106 ;; Arbitrary punctuation at the beginning of each line.
|
|
107 (while (string-match "^\\s-*\\s.+\\s-*" ct)
|
|
108 (setq ct (concat (substring ct 0 (match-beginning 0))
|
|
109 (substring ct (match-end 0)))))
|
|
110 ;; End of a block comment.
|
|
111 (if (and (boundp 'block-comment-end)
|
|
112 block-comment-end
|
|
113 (string-match block-comment-end ct))
|
|
114 (setq ct (concat (substring ct 0 (match-beginning 0))
|
|
115 (substring ct (match-end 0)))))
|
|
116 ;; In case it's a real string, STRIPIT.
|
|
117 (while (string-match "\\s-*\\s\"+\\s-*" ct)
|
|
118 (setq ct (concat (substring ct 0 (match-beginning 0))
|
|
119 (substring ct (match-end 0))))))
|
|
120 ;; Now return the text.
|
|
121 ct))))
|
|
122
|
|
123 (semantic-alias-obsolete 'semantic-find-documentation
|
|
124 'semantic-documentation-for-tag)
|
|
125
|
|
126 (provide 'semantic/doc)
|
|
127
|
|
128 ;;; semantic-doc.el ends here
|