| blob | 9d7e3ad9767350c60f7951107181db15c280aa9d |
1 ;;; srecode/document.el --- Documentation (comment) generation
3 ;; Copyright (C) 2008-2014 Free Software Foundation, Inc.
5 ;; Author: Eric M. Ludlam <eric@siege-engine.com>
7 ;; This file is part of GNU Emacs.
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
22 ;;; Commentary:
23 ;;
24 ;; Routines for fabricating human readable text from function and
25 ;; variable names as base-text for function comments. Document is not
26 ;; meant to generate end-text for any function. It is merely meant to
27 ;; provide some useful base words and text, and as a framework for
28 ;; managing comments.
29 ;;
30 ;;; Origins:
31 ;;
32 ;; Document was first written w/ cparse, a custom regexp based c parser.
33 ;;
34 ;; Document was then ported to cedet/semantic using sformat (super
35 ;; format) as the templating engine.
36 ;;
37 ;; Document has now been ported to srecode, using the semantic recoder
38 ;; as the templating engine.
40 ;; This file combines srecode/document.el and srecode/document-vars.el
41 ;; from the CEDET repository.
54 ;;; Code:
57 "File and tag browser frame."
62 '(
84 )
85 "List of common English abbreviations or full words.
86 These are nouns (as opposed to verbs) for use in creating expanded
87 versions of names. This is an alist with each element of the form:
88 (MATCH . RESULT)
89 MATCH is a regexp to match in the type field.
90 RESULT is a string."
96 '(
98 ;; trick to get re-alloc and alloc to pair into one sentence.
133 )
134 "List of names to string match against the function name.
135 This is an alist with each element of the form:
136 (MATCH . RESULT)
137 MATCH is a regexp to match in the type field.
138 RESULT is a string.
140 Certain prefixes may always mean the same thing, and the same comment
141 can be used as a beginning for the description. Regexp should be
142 lower case since the string they are compared to is downcased.
143 A string may end in a space, in which case, last-alist is searched to
144 see how best to describe what can be returned.
145 Doesn't always work correctly, but that is just because English
146 doesn't always work correctly."
152 '(
171 )
172 "List of common English abbreviations or full words.
173 These are nouns (as opposed to verbs) for use in creating expanded
174 versions of names. This is an alist with each element of the form:
175 (MATCH . RESULT)
176 MATCH is a regexp to match in the type field.
177 RESULT is a string."
183 '(
184 ;; Static must be first in the list to provide the intro to the sentence
187 )
188 "List of regexp matches for types.
189 They provide a little bit of text when typing information is
190 described.
191 This is an alist with each element of the form:
192 (MATCH . RESULT)
193 MATCH is a regexp to match in the type field.
194 RESULT is a string."
200 '(
209 )
210 "List of regexps which provide the type of the return value.
211 This is an alist with each element of the form:
212 (MATCH . RESULT)
213 MATCH is a regexp to match in the type field.
214 RESULT is a string, which can contain %s, which is replaced with
215 `match-string' 1."
228 )
229 "Alist of common variable names appearing as function parameters.
230 This is an alist with each element of the form:
231 (MATCH . RESULT)
232 MATCH is a regexp to match in the type field.
233 RESULT is a string of text to use to describe MATCH.
234 When one is encountered, document-insert-parameters will automatically
235 place this comment after the parameter name."
250 ;; How about some X things?
255 )
256 "Alist of input parameter types and strings describing them.
257 This is an alist with each element of the form:
258 (MATCH . RESULT)
259 MATCH is a regexp to match in the type field.
260 RESULT is a string."
265 ;;;###autoload
267 "Insert some comments.
268 Whack any comments that may be in the way and replace them.
269 If the region is active, then insert group function comments.
270 If the cursor is in a comment, figure out what kind of comment it is
271 and replace it.
272 If the cursor is in a function, insert a function comment.
273 If the cursor is on a one line prototype, then insert post-fcn comments."
284 ;; ELSE
286 ;; A declaration comment. Find what it documents.
289 ;; If we are on a one line tag/comment, go to that fcn.
294 ;; Else, do we have a fcn following us?
297 )
299 ;; Now analyze the tag we may be on.
303 ;; A one-line variable
307 ;; A plain function
310 ;; Don't know.
313 )
315 ;; ELSE, no tag. Perhaps we should just insert a nice section
316 ;; header??
323 ))))
326 "Insert a section comment with TITLE."
337 "section-comment"
338 "declaration"
348 ))
352 "Strip stray whitespace from around STR."
357 str)
359 ;;;###autoload
361 "Insert or replace a function comment.
362 FCN-IN is the Semantic tag of the function to add a comment too.
363 If FCN-IN is not provided, the current tag is used instead.
364 It is assumed that the comment occurs just in front of FCN-IN."
375 "function-comment"
376 "declaration"
381 ;; Try to figure out the tag we want to use.
393 ;; Find any existing doc strings.
401 )
414 )
420 )
426 ;; There are many possible states that comment could be in.
427 ;; Take a guess about what the user would like to do, and ask
428 ;; the right kind of question.
450 ))
451 )))
455 ;; Perform the insertion
460 dict "DOC"
462 doctext
464 )))
465 )
467 ))
468 ))
470 ;;;###autoload
472 "Insert or replace a variable comment.
473 VAR-IN is the Semantic tag of the function to add a comment too.
474 If VAR-IN is not provided, the current tag is used instead.
475 It is assumed that the comment occurs just after VAR-IN."
486 "variable-same-line-comment"
487 "declaration"
492 ;; Try to figure out the tag we want to use.
504 ;; Find any existing doc strings.
508 )
519 ;; Extract text from the existing comment.
524 ))
525 )
527 ;; Clean up the end of the line and use handy comment-column.
533 ;; Perform the insertion
539 tag))))
540 )
542 ))
543 )
545 ;;;###autoload
547 "Insert group comments around the active between BEG and END.
548 If the region includes only parts of some tags, expand out
549 to the beginning and end of the tags on the region.
550 If there is only one tag in the region, complain."
573 )
575 ;; If beg/end wrapped nothing, then tag-start,end would actually
576 ;; point at some odd stuff that is out of order.
581 tag-end nil))
584 ;; If tag-start and -end are the same, and it is a class or
585 ;; struct, try to find child tags inside the classdecl.
588 tag-start
593 )
597 )
601 )
602 )
605 ;; We are probably in a classdecl
606 ;; @todo -could I really use (srecode-calculate-context) ?
609 )
611 ;; Derive start and end locations based on the tags.
614 )
615 ;; Now load the templates
617 "group-comment-start"
618 context
621 "group-comment-end"
622 context
628 ;; Setup the name of this group ahead of time.
630 ;; @todo - guess at a name based on common strings
631 ;; of the tags in the group.
633 dict "GROUPNAME"
636 ;; Perform the insertion
637 ;; Do the end first so we don't need to recalculate anything.
638 ;;
647 ))
650 ;;; Document Generation Functions
651 ;;
652 ;; Routines for making up English style comments.
655 "Create documentation for the function defined in TAG.
656 If we can identify a verb in the list followed by some
657 name part then check the return value to see if we can use that to
658 finish off the sentence. That is, any function with 'alloc' in it will be
659 allocating something based on its type."
667 ;; convert a type list into a long string to analyze.
669 ;; check for modifiers like static
677 ;; check for verb parts!
685 ;; if we end in a space, then we are expecting a potential
686 ;; return value.
691 ;; check for noun parts!
701 ;; add trailers to names which are obviously returning something.
710 ;; this one may use parts of the return value.
717 news))
720 "Convert tag or string PARAM into a name,comment pair.
721 Optional COMMENTLIST is list of previously existing comments to
722 use instead in alist form. If the name doesn't appear in the list of
723 standard names, then english it instead."
729 ;; Make sure the type is a string.
732 ;; Find name description parts.
740 nil
741 ;; finally check for array parts
749 ;; Convert from programmer to english.
753 cmt))
756 "Take PROGRAMMER and convert it into English.
757 Works with the following rules:
758 1) convert all _ into spaces.
759 2) inserts spaces between CamelCasing word breaks.
760 3) expands noun names based on common programmer nouns.
762 This function is designed for variables, not functions. This does
763 not account for verb parts."
765 ""
770 ;;
771 ;; 1) Convert underscores
772 ;;
779 newstr nil
781 ;;
782 ;; 2) Find word breaks between case changes
783 ;;
798 ;;
799 ;; 3) Expand the words if possible
800 ;;
802 ind 0
803 programmer newstr
804 newstr nil)
814 ;; don't terminate because we may actually have 2 words
815 ;; next to each other we didn't identify before
821 newstr)))
823 ;;; UTILS
824 ;;
826 "Does TAG fit on one line with space on the end?"
835 ;; Local variables:
836 ;; generated-autoload-file: "loaddefs.el"
837 ;; generated-autoload-load-name: "srecode/document"
838 ;; End:
840 ;;; srecode/document.el ends here