Comment récupérer des docstrings à partir de fonctions et de variables?

J'essaie d'écrire une fonction qui récupérera les docstrings de n'importe quel sexps dans un fichier qui correspond (def.*).

Je voudrais pouvoir à la fois récupérer toutes les fonctions / macros, ainsi que toutes les variables définies. Pour les variables, je voudrais la docstring, tandis que pour toutes les fonctions, je voudrais également les listes d'arguments.

elisp doc-strings

— Jonathan Leech-Pepin
source

Pour clarifier: avez-vous un fichier source Elisp (mon interprétation), ou avez-vous un tas de variables et de fonctions dans l'environnement Emacs actuel (interprétation de Constantine)? Et si la première interprétation, voulez-vous vraiment tous les (def…)sexps, pas seulement des spécifications de haut niveau? Ou l'interprétation intermédiaire des fonctions et des variables qui seraient définies si le fichier était chargé? Ou une définition plus détendue qui inclut des formes de niveau supérieur telles que (when nil (defun …)))?

— Gilles 'SO- arrête d'être méchant'

J'avais initialement voulu le premier, mais sur la base de l'interprétation de Constantine, j'ai pu obtenir une implémentation fonctionnelle qui m'a obtenu ce dont j'avais besoin. Le but est de convertir la source elisp en documentation (écrite en Org) basée sur Docstrings.

— Jonathan Leech-Pepin

Avec la deuxième interprétation, le intégré describe-functionet les amis font une bonne partie de ce que vous voulez (docstring et liste d'arguments).

— T. Verron

Si l'objectif est d'obtenir des informations sur les fonctions et variables déjà présentes dans l'environnement :

Pour les docstrings de fonctions et de macros, voir la documentationfonction.
Pour les docstrings variables, utilisez documentation-property; par exemple:
```
(documentation-property
 'user-init-file 'variable-documentation)
```
Pour l'arité de la fonction et la liste des arguments, consultez cette question Emacs.SE , la réponse et les commentaires sur la question.

(J'ai trouvé cela en appuyant C-h k C-h fet en survolant le code source de describe-function(idem pour les docstrings variables, mais en étudiant describe-variable).)

Pour analyser un fichier de code source Emacs Lisp, en supposant que le but est d'obtenir des informations sur les def.*formulaires de niveau supérieur , on peut faire quelque chose de semblable au suivant.

(defun get-defun-info (buffer)
  "Get information about all `defun' top-level sexps in a buffer
BUFFER. Returns a list with elements of the form (symbol args docstring)."
  (with-current-buffer buffer
    (save-excursion
      (save-restriction
        (widen)
        (goto-char (point-min))
        (let (result)
          ;; keep going while reading succeeds
          (while (condition-case nil
                     (progn
                       (read (current-buffer))
                       (forward-sexp -1)
                       t)
                   (error nil))
            (let ((form (read (current-buffer))))
              (cond
               ((not (listp form))      ; if it's not a list, skip it
                nil)
               ((eq (nth 0 form) 'defun) ; if it's a defun, collect info
                (let ((sym (nth 1 form))
                      (args (nth 2 form))
                      (doc (when (stringp (nth 3 form)) (nth 3 form))))
                  (push (list sym args doc) result))))))
          result)))))

Ceci peut être facilement étendu à defvar, defconstetc.

Pour gérer l' defunapparition à l' intérieur de formulaires de niveau supérieur, il faudrait descendre dans ces formulaires, éventuellement en utilisant la récursivité.

— Constantine
source

+1 pour indiquer aux lecteurs comment trouver eux-mêmes ces informations. C'est la leçon la plus importante des deux que vous avez enseignée.

— Drew

@Drew Il semble que nous soyons dans une situation étrange: le but de ce site est de se rendre obsolète… Cela ferait une discussion intéressante dans le chat :)

— Sean Allred

@SeanAllred Apprendre aux gens à apprendre n'arrête pas les questions, mais les améliore.

— Malabarba

+1 à Malabarba. Le but de ce site devrait (à mon humble avis) être de répondre à ce qu'Emacs lui-même ne peut pas répondre ou ne répond pas bien ou facilement . Analogie: Pour la langue et l'utilisation du site en anglais, une des raisons de la fermeture des questions est que "les questions auxquelles il est possible de répondre en utilisant des références couramment disponibles sont hors sujet *". (StackOverflow est similaire.) Nous ne devons pas être aussi extrêmes, en disant que les questions auxquelles Emacs lui-même peut répondre sont hors sujet , mais la même idée devrait s'appliquer: amener les utilisateurs à essayer de trouver la réponse en premier . Dans notre cas, cela signifie en demandant à Emacs .

— Drew

@Drew Fair points :)

— Sean Allred