Commits

Aidan Kehoe  committed 51d7226

Uncomment docstrings, advice.el.

2012-05-11 Aidan Kehoe <kehoea@parhasard.net>

* advice.el (ad-pushnew-advised-function):
* advice.el (ad-pop-advised-function):
* advice.el (ad-do-advised-functions):
* advice.el (ad-is-advised):
* advice.el (ad-initialize-advice-info):
* advice.el (ad-get-advice-info-field):
* advice.el (ad-set-advice-info-field):
* advice.el (ad-is-active):
* advice.el (ad-has-enabled-advice):
* advice.el (ad-has-redefining-advice):
* advice.el (ad-has-any-advice):
* advice.el (ad-get-enabled-advices):
* advice.el (ad-safe-fset):
* advice.el (ad-make-origname):
* advice.el (ad-read-advised-function):
* advice.el (ad-read-advice-class):
* advice.el (ad-read-advice-name):
* advice.el (ad-read-advice-specification):
* advice.el (ad-read-regexp):
* advice.el (ad-find-advice):
* advice.el (ad-advice-position):
* advice.el (ad-compiled-p):
* advice.el (ad-compiled-code):
* advice.el (ad-lambda-expression):
* advice.el (ad-arglist):
* advice.el (ad-subr-arglist):
* advice.el (ad-docstring):
* advice.el (ad-interactive-form):
* advice.el (ad-body-forms):
* advice.el (ad-make-advised-definition-docstring):
* advice.el (ad-advised-definition-p):
* advice.el (ad-definition-type):
* advice.el (ad-has-proper-definition):
* advice.el (ad-real-definition):
* advice.el (ad-real-orig-definition):
* advice.el (ad-is-compilable):
* advice.el (ad-compile-function):
* advice.el (ad-parse-arglist):
* advice.el (ad-retrieve-args-form):
* advice.el (ad-access-argument):
* advice.el (ad-get-argument):
* advice.el (ad-set-argument):
* advice.el (ad-get-arguments):
* advice.el (ad-set-arguments):
* advice.el (ad-insert-argument-access-forms):
* advice.el (ad-make-mapped-call):
* advice.el (ad-make-advised-docstring):
* advice.el (ad-advised-arglist):
* advice.el (ad-advised-interactive-form):
* advice.el (ad-make-advised-definition):
* advice.el (ad-make-hook-form):
* advice.el (ad-make-cache-id):
* advice.el (ad-get-cache-class-id):
* advice.el (ad-verify-cache-id):
* advice.el (ad-preactivate-advice):
* advice.el (ad-should-compile):
* advice.el (ad-activate-advised-definition):
Uncomment the docstrings for these functions, they take up negligible
space these days.

  • Participants
  • Parent commits d56f8e5

Comments (0)

Files changed (2)

+2012-05-11  Aidan Kehoe  <kehoea@parhasard.net>
+
+	* advice.el (ad-pushnew-advised-function):
+	* advice.el (ad-pop-advised-function):
+	* advice.el (ad-do-advised-functions):
+	* advice.el (ad-is-advised):
+	* advice.el (ad-initialize-advice-info):
+	* advice.el (ad-get-advice-info-field):
+	* advice.el (ad-set-advice-info-field):
+	* advice.el (ad-is-active):
+	* advice.el (ad-has-enabled-advice):
+	* advice.el (ad-has-redefining-advice):
+	* advice.el (ad-has-any-advice):
+	* advice.el (ad-get-enabled-advices):
+	* advice.el (ad-safe-fset):
+	* advice.el (ad-make-origname):
+	* advice.el (ad-read-advised-function):
+	* advice.el (ad-read-advice-class):
+	* advice.el (ad-read-advice-name):
+	* advice.el (ad-read-advice-specification):
+	* advice.el (ad-read-regexp):
+	* advice.el (ad-find-advice):
+	* advice.el (ad-advice-position):
+	* advice.el (ad-compiled-p):
+	* advice.el (ad-compiled-code):
+	* advice.el (ad-lambda-expression):
+	* advice.el (ad-arglist):
+	* advice.el (ad-subr-arglist):
+	* advice.el (ad-docstring):
+	* advice.el (ad-interactive-form):
+	* advice.el (ad-body-forms):
+	* advice.el (ad-make-advised-definition-docstring):
+	* advice.el (ad-advised-definition-p):
+	* advice.el (ad-definition-type):
+	* advice.el (ad-has-proper-definition):
+	* advice.el (ad-real-definition):
+	* advice.el (ad-real-orig-definition):
+	* advice.el (ad-is-compilable):
+	* advice.el (ad-compile-function):
+	* advice.el (ad-parse-arglist):
+	* advice.el (ad-retrieve-args-form):
+	* advice.el (ad-access-argument):
+	* advice.el (ad-get-argument):
+	* advice.el (ad-set-argument):
+	* advice.el (ad-get-arguments):
+	* advice.el (ad-set-arguments):
+	* advice.el (ad-insert-argument-access-forms):
+	* advice.el (ad-make-mapped-call):
+	* advice.el (ad-make-advised-docstring):
+	* advice.el (ad-advised-arglist):
+	* advice.el (ad-advised-interactive-form):
+	* advice.el (ad-make-advised-definition):
+	* advice.el (ad-make-hook-form):
+	* advice.el (ad-make-cache-id):
+	* advice.el (ad-get-cache-class-id):
+	* advice.el (ad-verify-cache-id):
+	* advice.el (ad-preactivate-advice):
+	* advice.el (ad-should-compile):
+	* advice.el (ad-activate-advised-definition):
+	Uncomment the docstrings for these functions, they take up negligible
+	space these days.
+
 2012-01-10  Norbert Koch  <viteno@xemacs.org>
 
 	* Makefile (VERSION): XEmacs package 2.31 released.
 (defvar ad-advised-functions nil)
 
 (defmacro ad-pushnew-advised-function (function)
-  ;;"Add FUNCTION to `ad-advised-functions' unless its already there."
+  "Add FUNCTION to `ad-advised-functions' unless its already there."
   (` (if (not (assoc (symbol-name (, function)) ad-advised-functions))
 	 (setq ad-advised-functions
 	       (cons (list (symbol-name (, function)))
 		     ad-advised-functions)))))
 
 (defmacro ad-pop-advised-function (function)
-  ;;"Remove FUNCTION from `ad-advised-functions'."
+  "Remove FUNCTION from `ad-advised-functions'."
   (` (setq ad-advised-functions
 	   (delq (assoc (symbol-name (, function)) ad-advised-functions)
 		 ad-advised-functions))))
 
 (defmacro ad-do-advised-functions (varform &rest body)
-  ;;"`dolist'-style iterator that maps over `ad-advised-functions'.
-  ;;     (ad-do-advised-functions (VAR [RESULT-FORM])
-  ;;         BODY-FORM...)
-  ;;Also see `dolist'.  On each iteration VAR will be bound to the
-  ;;name of an advised function (a symbol)."
+  "`dolist'-style iterator that maps over `ad-advised-functions'.
+     (ad-do-advised-functions (VAR [RESULT-FORM])
+         BODY-FORM...)
+Also see `dolist'.  On each iteration VAR will be bound to the
+name of an advised function (a symbol)."
   (` (dolist ((, (car varform))
 		 ad-advised-functions
 		 (, (car (cdr varform))))
   (` (copy-tree (get (, function) 'ad-advice-info))))
 
 (defmacro ad-is-advised (function)
-  ;;"Returns non-nil if FUNCTION has any advice info associated with it.
-  ;;This does not mean that the advice is also active."
+  "Return non-nil if FUNCTION has any advice info associated with it.
+This does not mean that the advice is also active."
   (list 'ad-get-advice-info function))
 
 (defun ad-initialize-advice-info (function)
-  ;;"Initializes the advice info for FUNCTION.
-  ;;Assumes that FUNCTION has not yet been advised."
+  "Initializes the advice info for FUNCTION.
+Assumes that FUNCTION has not yet been advised."
   (ad-pushnew-advised-function function)
   (ad-set-advice-info function (list (cons 'active nil))))
 
 (defmacro ad-get-advice-info-field (function field)
-  ;;"Retrieves the value of the advice info FIELD of FUNCTION."
+  "Retrieves the value of the advice info FIELD of FUNCTION."
   (` (cdr (assq (, field) (ad-get-advice-info (, function))))))
 
 (defun ad-set-advice-info-field (function field value)
-  ;;"Destructively modifies VALUE of the advice info FIELD of FUNCTION."
+  "Destructively modifies VALUE of the advice info FIELD of FUNCTION."
   (and (ad-is-advised function)
        (cond ((assq field (ad-get-advice-info function))
 	      ;; A field with that name is already present:
 
 ;; Don't make this a macro so we can use it as a predicate:
 (defun ad-is-active (function)
-  ;;"non-nil if FUNCTION is advised and activated."
+  "Return non-nil if FUNCTION is advised and activated."
   (ad-get-advice-info-field function 'active))
 
 
 (defvar ad-advice-classes '(before around after activation deactivation))
 
 (defun ad-has-enabled-advice (function class)
-  ;;"True if at least one of FUNCTION's advices in CLASS is enabled."
+  "True if at least one of FUNCTION's advices in CLASS is enabled."
   (dolist (advice (ad-get-advice-info-field function class))
     (if (ad-advice-enabled advice) (return t))))
 
 (defun ad-has-redefining-advice (function)
-  ;;"True if FUNCTION's advice info defines at least 1 redefining advice.
-  ;;Redefining advices affect the construction of an advised definition."
+  "True if FUNCTION's advice info defines at least 1 redefining advice.
+Redefining advices affect the construction of an advised definition."
   (and (ad-is-advised function)
        (or (ad-has-enabled-advice function 'before)
 	   (ad-has-enabled-advice function 'around)
 	   (ad-has-enabled-advice function 'after))))
 
 (defun ad-has-any-advice (function)
-  ;;"True if the advice info of FUNCTION defines at least one advice."
+  "True if the advice info of FUNCTION defines at least one advice."
   (and (ad-is-advised function)
        (dolist (class ad-advice-classes nil)
 	 (if (ad-get-advice-info-field function class)
 	     (return t)))))
 
 (defun ad-get-enabled-advices (function class)
-  ;;"Returns the list of enabled advices of FUNCTION in CLASS."
+  "Returns the list of enabled advices of FUNCTION in CLASS."
   (let (enabled-advices)
     (dolist (advice (ad-get-advice-info-field function class))
       (if (ad-advice-enabled advice)
        (,@ body))))
 
 (defun ad-safe-fset (symbol definition)
-  ;; A safe `fset' which will never call `ad-activate' recursively.
+  "A safe `fset' which will never call `ad-activate' recursively."
   (ad-with-auto-activation-disabled
    (ad-real-fset symbol definition)))
 
 ;; we need to use `ad-real-orig-definition'.
 
 (defun ad-make-origname (function)
-  ;;"Makes name to be used to call the original FUNCTION."
+  "Make name to be used to call the original FUNCTION."
   (intern (format "ad-Orig-%s" function)))
 
 (defmacro ad-get-orig-definition (function)
 ;; ===============================
 
 (defun ad-read-advised-function (&optional prompt predicate default)
-  ;;"Reads name of advised function with completion from the minibuffer.
-  ;;An optional PROMPT will be used to prompt for the function.  PREDICATE
-  ;;plays the same role as for `try-completion' (which see).  DEFAULT will
-  ;;be returned on empty input (defaults to the first advised function for
-  ;;which PREDICATE returns non-nil)."
+  "Read name of advised function with completion from the minibuffer.
+An optional PROMPT will be used to prompt for the function.  PREDICATE
+plays the same role as for `try-completion' (which see).  DEFAULT will
+be returned on empty input (defaults to the first advised function for
+which PREDICATE returns non-nil)."
   (if (null ad-advised-functions)
       (error "ad-read-advised-function: There are no advised functions"))
   (setq default
 	  ad-advice-classes))
 
 (defun ad-read-advice-class (function &optional prompt default)
-  ;;"Reads a legal advice class with completion from the minibuffer.
-  ;;An optional PROMPT will be used to prompt for the class.  DEFAULT will
-  ;;be returned on empty input (defaults to the first non-empty advice
-  ;;class of FUNCTION)."
+  "Read a legal advice class with completion from the minibuffer.
+An optional PROMPT will be used to prompt for the class.  DEFAULT will
+be returned on empty input (defaults to the first non-empty advice
+class of FUNCTION)."
   (setq default
 	(or default
 	    (dolist (class ad-advice-classes)
       (intern class))))
 
 (defun ad-read-advice-name (function class &optional prompt)
-  ;;"Reads name of existing advice of CLASS for FUNCTION with completion.
-  ;;An optional PROMPT is used to prompt for the name."
+  "Reads name of existing advice of CLASS for FUNCTION with completion.
+An optional PROMPT is used to prompt for the name."
   (let* ((name-completion-table
           (mapcar (function (lambda (advice)
 			      (list (symbol-name (ad-advice-name advice)))))
       (intern name))))
 
 (defun ad-read-advice-specification (&optional prompt)
-  ;;"Reads a complete function/class/name specification from minibuffer.
-  ;;The list of read symbols will be returned.  The optional PROMPT will
-  ;;be used to prompt for the function."
+  "Reads a complete function/class/name specification from minibuffer.
+The list of read symbols will be returned.  The optional PROMPT will
+be used to prompt for the function."
   (let* ((function (ad-read-advised-function prompt))
 	 (class (ad-read-advice-class function))
 	 (name (ad-read-advice-name function class)))
 (defvar ad-last-regexp "")
 
 (defun ad-read-regexp (&optional prompt)
-  ;;"Reads a regular expression from the minibuffer."
+  "Read a regular expression from the minibuffer."
   (let ((regexp (read-from-minibuffer
 		 (concat (or prompt "Regular expression: ")
 			 (if (equal ad-last-regexp "") ""
 ;; ===========================================================
 
 (defmacro ad-find-advice (function class name)
-  ;;"Finds the first advice of FUNCTION in CLASS with NAME."
+  "Find the first advice of FUNCTION in CLASS with NAME."
   (` (assq (, name) (ad-get-advice-info-field (, function) (, class)))))
 
 (defun ad-advice-position (function class name)
-  ;;"Returns position of first advice of FUNCTION in CLASS with NAME."
+  "Return position of first advice of FUNCTION in CLASS with NAME."
   (let* ((found-advice (ad-find-advice function class name))
 	 (advices (ad-get-advice-info-field function class)))
     (if found-advice
     (ad-safe-fset 'byte-code-function-p 'compiled-function-p))
 
 (defmacro ad-compiled-p (definition)
-  ;;"non-nil if DEFINITION is a compiled byte-code object."
+  "Return non-nil if DEFINITION is a compiled byte-code object."
   (` (or (byte-code-function-p (, definition))
 	 (and (ad-macro-p (, definition))
 	      (byte-code-function-p (ad-lambdafy (, definition)))))))
 
 (defmacro ad-compiled-code (compiled-definition)
-  ;;"Returns the byte-code object of a COMPILED-DEFINITION."
+  "Return the byte-code object of a COMPILED-DEFINITION."
   (` (if (ad-macro-p (, compiled-definition))
 	 (ad-lambdafy (, compiled-definition))
        (, compiled-definition))))
 
 (defun ad-lambda-expression (definition)
-  ;;"Returns the lambda expression of a function/macro/advice DEFINITION."
+  "Return the lambda expression of a function/macro/advice DEFINITION."
   (cond ((ad-lambda-p definition)
 	 definition)
 	((ad-macro-p definition)
 	(t nil)))
 
 (defun ad-arglist (definition &optional name)
-  ;;"Returns the argument list of DEFINITION.
-  ;;If DEFINITION could be from a subr then its NAME should be
-  ;;supplied to make subr arglist lookup more efficient."
+  "Return the argument list of DEFINITION.
+If DEFINITION could be from a subr then its NAME should be
+supplied to make subr arglist lookup more efficient."
   (cond ((ad-compiled-p definition)
 	 ;; XEmacs fix:
 	 (if (featurep 'xemacs)
   (` (car (get (, subr) 'ad-subr-arglist))))
 
 (defun ad-subr-arglist (subr-name)
-  ;;"Retrieve arglist of the subr with SUBR-NAME.
-  ;;Either use the one stored under the `ad-subr-arglist' property,
-  ;;or try to retrieve it from the docstring and cache it under
-  ;;that property, or otherwise use `(&rest ad-subr-args)'."
+  "Retrieve arglist of the subr with SUBR-NAME.
+Either use the one stored under the `ad-subr-arglist' property,
+or try to retrieve it from the docstring and cache it under
+that property, or otherwise use `(&rest ad-subr-args)'."
   (cond ((ad-subr-args-defined-p subr-name)
 	 (ad-get-subr-args subr-name))
 	;; says jwz: Should use this for Lemacs 19.8 and above:
 		   (t '(&rest ad-subr-args)))))))
 
 (defun ad-docstring (definition)
-  ;;"Returns the unexpanded docstring of DEFINITION."
+  "Return the unexpanded docstring of DEFINITION."
   (let ((docstring
 	 (if (ad-compiled-p definition)
 	     (ad-real-documentation definition t)
 	docstring)))
 
 (defun ad-interactive-form (definition)
-  ;;"Returns the interactive form of DEFINITION."
+  "Return the interactive form of DEFINITION."
   (cond ((ad-compiled-p definition)
 	 (and (commandp definition)
 	      ;; XEmacs: we have an accessor function so don't use aref.
 	 (commandp (ad-lambda-expression definition)))))
 
 (defun ad-body-forms (definition)
-  ;;"Returns the list of body forms of DEFINITION."
+  "Return the list of body forms of DEFINITION."
   (cond ((ad-compiled-p definition)
 	 nil)
 	((consp definition)
 (defvar ad-advised-definition-docstring-regexp "^\\$ad-doc: \\(.+\\)\\$$")
 
 (defun ad-make-advised-definition-docstring (function)
-  ;; Makes an identifying docstring for the advised definition of FUNCTION.
-  ;; Put function name into the documentation string so we can infer
-  ;; the name of the advised function from the docstring.  This is needed
-  ;; to generate a proper advised docstring even if we are just given a
-  ;; definition (also see the defadvice for `documentation'):
+  "Make an identifying docstring for the advised definition of FUNCTION.
+Put function name into the documentation string so we can infer
+the name of the advised function from the docstring.  This is needed
+to generate a proper advised docstring even if we are just given a
+definition (also see the defadvice for `documentation')."
   (format "$ad-doc: %s$" (prin1-to-string function)))
 
 (defun ad-advised-definition-p (definition)
-  ;;"non-nil if DEFINITION was generated from advice information."
+  "Return non-nil if DEFINITION was generated from advice information."
   (if (or (ad-lambda-p definition)
 	  (ad-macro-p definition)
 	  (ad-compiled-p definition))
 	      ad-advised-definition-docstring-regexp docstring)))))
 
 (defun ad-definition-type (definition)
-  ;;"Returns symbol that describes the type of DEFINITION."
+  "Return symbol that describes the type of DEFINITION."
   (if (ad-macro-p definition)
       'macro
     (if (ad-subr-p definition)
 	    'advice)))))
 
 (defun ad-has-proper-definition (function)
-  ;;"True if FUNCTION is a symbol with a proper definition.
-  ;;For that it has to be fbound with a non-autoload definition."
+  "True if FUNCTION is a symbol with a proper definition.
+For that it has to be fbound with a non-autoload definition."
   (and (symbolp function)
        (fboundp function)
        (not (eq (car-safe (symbol-function function)) 'autoload))))
 ;; The following two are necessary for the sake of packages such as
 ;; ange-ftp which redefine functions via fcell indirection:
 (defun ad-real-definition (function)
-  ;;"Finds FUNCTION's definition at the end of function cell indirection."
+  "Find FUNCTION's definition at the end of function cell indirection."
   (if (ad-has-proper-definition function)
       (let ((definition (symbol-function function)))
 	(if (symbolp definition)
 	  definition))))
 
 (defun ad-real-orig-definition (function)
-  ;;"Finds FUNCTION's real original definition starting from its `origname'."
+  "Find FUNCTION's real original definition starting from its `origname'."
   (if (ad-is-advised function)
       (ad-real-definition (ad-get-advice-info-field function 'origname))))
 
 (defun ad-is-compilable (function)
-  ;;"True if FUNCTION has an interpreted definition that can be compiled."
+  "True if FUNCTION has an interpreted definition that can be compiled."
   (and (ad-has-proper-definition function)
        (or (ad-lambda-p (symbol-function function))
 	   (ad-macro-p (symbol-function function)))
        (not (ad-compiled-p (symbol-function function)))))
 
 (defun ad-compile-function (function)
-  "Byte-compiles FUNCTION (or macro) if it is not yet compiled."
+  "Byte-compile FUNCTION (or macro) if it is not yet compiled."
   (interactive "aByte-compile function: ")
   (if (ad-is-compilable function)
       ;; Need to turn off auto-activation
 ;; =============================
 
 (defun ad-parse-arglist (arglist)
-  ;;"Parses ARGLIST into its required, optional and rest parameters.
-  ;;A three-element list is returned, where the 1st element is the list of
-  ;;required arguments, the 2nd is the list of optional arguments, and the 3rd
-  ;;is the name of an optional rest parameter (or nil)."
+  "Parse ARGLIST into its required, optional and rest parameters.
+A three-element list is returned, where the 1st element is the list of
+required arguments, the 2nd is the list of optional arguments, and the 3rd
+is the name of an optional rest parameter (or nil)."
   (let* (required optional rest)
     (setq rest (car (cdr (memq '&rest arglist))))
     (if rest (setq arglist (reverse (cdr (memq '&rest (reverse arglist))))))
     (list required optional rest)))
 
 (defun ad-retrieve-args-form (arglist)
-  ;;"Generates a form which evaluates into names/values/types of ARGLIST.
-  ;;When the form gets evaluated within a function with that argument list
-  ;;it will result in a list with one entry for each argument, where the
-  ;;first element of each entry is the name of the argument, the second
-  ;;element is its actual current value, and the third element is either
-  ;;`required', `optional' or `rest' depending on the type of the argument."
+  "Generate a form which evaluates into names/values/types of ARGLIST.
+When the form gets evaluated within a function with that argument list
+it will result in a list with one entry for each argument, where the
+first element of each entry is the name of the argument, the second
+element is its actual current value, and the third element is either
+`required', `optional' or `rest' depending on the type of the argument."
   (let* ((parsed-arglist (ad-parse-arglist arglist))
 	 (rest (nth 2 parsed-arglist)))
     (` (list
 	(t (list 'nth position list))))
 
 (defun ad-access-argument (arglist index)
-  ;;"Tells how to access ARGLIST's actual argument at position INDEX.
-  ;;For a required/optional arg it simply returns it, if a rest argument has
-  ;;to be accessed, it returns a list with the index and name."
+  "Tells how to access ARGLIST's actual argument at position INDEX.
+For a required/optional arg it simply returns it, if a rest argument has
+to be accessed, it returns a list with the index and name."
   (let* ((parsed-arglist (ad-parse-arglist arglist))
 	 (reqopt-args (append (nth 0 parsed-arglist)
 			      (nth 1 parsed-arglist)))
 	   (list (- index (length reqopt-args)) rest-arg)))))
 
 (defun ad-get-argument (arglist index)
-  ;;"Returns form to access ARGLIST's actual argument at position INDEX."
+  "Returns form to access ARGLIST's actual argument at position INDEX."
   (let ((argument-access (ad-access-argument arglist index)))
     (cond ((consp argument-access)
 	   (ad-element-access
 	  (argument-access))))
 
 (defun ad-set-argument (arglist index value-form)
-  ;;"Returns form to set ARGLIST's actual arg at INDEX to VALUE-FORM."
+  "Returns form to set ARGLIST's actual arg at INDEX to VALUE-FORM."
   (let ((argument-access (ad-access-argument arglist index)))
     (cond ((consp argument-access)
 	   ;; should this check whether there actually is something to set?
 		    index arglist)))))
 
 (defun ad-get-arguments (arglist index)
-  ;;"Returns form to access all actual arguments starting at position INDEX."
+  "Returns form to access all actual arguments starting at position INDEX."
   (let* ((parsed-arglist (ad-parse-arglist arglist))
 	 (reqopt-args (append (nth 0 parsed-arglist)
 			      (nth 1 parsed-arglist)))
     args-form))
 
 (defun ad-set-arguments (arglist index values-form)
-  ;;"Makes form to assign elements of VALUES-FORM as actual ARGLIST args.
-  ;;The assignment starts at position INDEX."
+  "Makes form to assign elements of VALUES-FORM as actual ARGLIST args.
+The assignment starts at position INDEX."
   (let ((values-index 0)
 	argument-access set-forms)
     (while (setq argument-access (ad-access-argument arglist index))
 	     (, 'ad-vAlUeS)))))))
 
 (defun ad-insert-argument-access-forms (definition arglist)
-  ;;"Expands arg-access text macros in DEFINITION according to ARGLIST."
+  "Expand arg-access text macros in DEFINITION according to ARGLIST."
   (macrolet
       ((subtree-test (form)
          `(funcall #'(lambda (form)
 						  source-reqopt-args)))))))))
 
 (defun ad-make-mapped-call (source-arglist target-arglist target-function)
-  ;;"Makes form to call TARGET-FUNCTION with args from SOURCE-ARGLIST."
+  "Make form to call TARGET-FUNCTION with args from SOURCE-ARGLIST."
   (let* ((mapped-form (ad-map-arglists source-arglist target-arglist)))
     (if (eq (car mapped-form) 'funcall)
 	(cons target-function (cdr (cdr mapped-form)))
 		     (or advice-docstring ""))))))
 
 (defun ad-make-advised-docstring (function &optional style)
-  ;;"Constructs a documentation string for the advised FUNCTION.
-  ;;It concatenates the original documentation with the documentation
-  ;;strings of the individual pieces of advice which will be formatted
-  ;;according to STYLE.  STYLE can be `plain' or `freeze', everything else
-  ;;will be interpreted as `default'.  The order of the advice documentation
-  ;;strings corresponds to before/around/after and the individual ordering
-  ;;in any of these classes."
+  "Construct a documentation string for the advised FUNCTION.
+It concatenates the original documentation with the documentation
+strings of the individual pieces of advice which will be formatted
+according to STYLE.  STYLE can be `plain' or `freeze', everything else
+will be interpreted as `default'.  The order of the advice documentation
+strings corresponds to before/around/after and the individual ordering
+in any of these classes."
   (let* ((origdef (ad-real-orig-definition function))
 	 (origtype (symbol-name (ad-definition-type origdef)))
 	 (origdoc
 ;; ========================================================
 
 (defun ad-advised-arglist (function)
-  ;;"Finds first defined arglist in FUNCTION's redefining advices."
+  "Find first defined arglist in FUNCTION's redefining advices."
   (dolist (advice (append (ad-get-enabled-advices function 'before)
 			     (ad-get-enabled-advices function 'around)
 			     (ad-get-enabled-advices function 'after)))
 	  (return arglist)))))
 
 (defun ad-advised-interactive-form (function)
-  ;;"Finds first interactive form in FUNCTION's redefining advices."
+  "Find first interactive form in FUNCTION's redefining advices."
   (dolist (advice (append (ad-get-enabled-advices function 'before)
 			     (ad-get-enabled-advices function 'around)
 			     (ad-get-enabled-advices function 'after)))
 ;; ============================
 
 (defun ad-make-advised-definition (function)
-  ;;"Generates an advised definition of FUNCTION from its advice info."
+  "Generate an advised definition of FUNCTION from its advice info."
   (if (and (ad-is-advised function)
 	   (ad-has-redefining-advice function))
       (let* ((origdef (ad-real-orig-definition function))
 
 ;; This is needed for activation/deactivation hooks:
 (defun ad-make-hook-form (function hook-name)
-  ;;"Makes hook-form from FUNCTION's advice bodies in class HOOK-NAME."
+  "Make hook-form from FUNCTION's advice bodies in class HOOK-NAME."
   (let ((hook-forms
 	 (mapcar (function (lambda (advice)
 			     (ad-body-forms (ad-advice-definition advice))))
   (ad-set-advice-info-field function 'cache nil))
 
 (defun ad-make-cache-id (function)
-  ;;"Generates an identifying image of the current advices of FUNCTION."
+  "Generate an identifying image of the current advices of FUNCTION."
   (let ((original-definition (ad-real-orig-definition function))
 	(cached-definition (ad-get-cache-definition function)))
     (list (mapcar (function (lambda (advice) (ad-advice-name advice)))
 		     (ad-interactive-form cached-definition))))))
 
 (defun ad-get-cache-class-id (function class)
-  ;;"Returns the part of FUNCTION's cache id that identifies CLASS."
+  "Return the part of FUNCTION's cache id that identifies CLASS."
   (let ((cache-id (ad-get-cache-id function)))
     (if (eq class 'before)
 	(car cache-id)
     code))
 
 (defun ad-verify-cache-id (function)
-  ;;"True if FUNCTION's cache-id is compatible with its current advices."
+  "True if FUNCTION's cache-id is compatible with its current advices."
   (eq (ad-cache-id-verification-code function) 'verified))
 
 
 ;; advised definition will be generated.
 
 (defun ad-preactivate-advice (function advice class position)
-  ;;"Preactivates FUNCTION and returns the constructed cache."
+  "Preactivate FUNCTION and returns the constructed cache."
   (let* ((function-defined-p (fboundp function))
 	 (old-definition
 	  (if function-defined-p
 ;; ======================================
 
 (defun ad-should-compile (function compile)
-  ;;"Returns non-nil if the advised FUNCTION should be compiled.
-  ;;If COMPILE is non-nil and not a negative number then it returns t.
-  ;;If COMPILE is a negative number then it returns nil.
-  ;;If COMPILE is nil then the result depends on the value of
-  ;;`ad-default-compilation-action' (which see)."
+  "Return non-nil if the advised FUNCTION should be compiled.
+If COMPILE is non-nil and not a negative number then it returns t.
+If COMPILE is a negative number then it returns nil.
+If COMPILE is nil then the result depends on the value of
+`ad-default-compilation-action' (which see)."
   (if (integerp compile)
       (>= compile 0)
     (if compile
 	    (t (featurep 'byte-compile))))))
 
 (defun ad-activate-advised-definition (function compile)
-  ;;"Redefines FUNCTION with its advised definition from cache or scratch.
-  ;;The resulting FUNCTION will be compiled if `ad-should-compile' returns t.
-  ;;The current definition and its cache-id will be put into the cache."
+  "Redefine FUNCTION with its advised definition from cache or scratch.
+The resulting FUNCTION will be compiled if `ad-should-compile' returns t.
+The current definition and its cache-id will be put into the cache."
   (let ((verified-cached-definition
 	 (if (ad-verify-cache-id function)
 	     (ad-get-cache-definition function))))