2015-11-18 83 views
7

Ho cercato su Google una manciata di elementi come "stringhe di documentazione lisp", "commenti chiari" e alcuni altri e non riesco a trovare nulla che tratti specificamente questo.Stringhe nel mezzo di Lisp S-exp?

Vedo un sacco di codice (soprattutto in CL e elisp) che assomiglia

(defvar test 1 
    "This is a quoted string and it says things" 
) 

Dove io normalmente fare

; This is a comment 
(defvar test 1) 

che è preferito? Ognuno di loro ha uno scopo diverso? Grazie!

+0

La documentazione di [defvar] (http://www.lispworks.com/documentation/HyperSpec/Body/m_defpar.htm) dice che la sintassi è "nome defvar [valore iniziale [documentazione]] => nome" e che "documentazione --- una stringa, non valutata." –

risposta

8

Molti oggetti in Common Lisp possono avere una stringa di documentazione, che può essere recuperato con la funzione generica documentation e impostare con la funzione generica (setf documentation). In base allo specification:

Le stringhe di documentazione sono disponibili per il debug. I programmi conformi possono utilizzare le stringhe di documentazione quando sono presenti, ma non devono dipendere dal loro comportamento corretto sulla presenza di quelle stringhe di documentazione. Un'implementazione è autorizzata a scartare le stringhe della documentazione in qualsiasi momento per ragioni definite dall'implementazione.

Quindi il primo caso permette di definire una variabile insieme alla stringa di documentazione, che può essere utilizzata per memorizzare in fase di esecuzione, se i permessi di attuazione così, le informazioni utili ai fini della documentazione e debugging, utilizzati sia tramite l'IDE, o direttamente, tramite una forma come:

(documentation 'test 'variable) 

il secondo caso, invece, è solo un commento all'interno di un file sorgente, utile solo per il consumo umano, ed è completamente ignorati dal lettore/compilatore il sistema.

2

Non hai provato a vedere hyperspec per defvar?

defvar accetta un argomento facoltativo - stringa di documento e questo è ciò di cui stai parlando.

documentazione specificata in questo modo può essere acessed throug documentation:

CL-USER> (defvar *a* "A variable" "A docstring") 
*A* 
CL-USER> (documentation '*a* 'variable) 
"A docstring" 
5

Gli ambienti di sviluppo utilizzeranno queste funzionalità di documentazione. Ad esempio GNU Emacs/SLIME:

Spostare il cursore di testo sul simbolo test.

Tipo c-c c-d c-d (Descrivi il simbolo).

Ora SLIME visualizza un buffer con il seguente contenuto:

COMMON-LISP-USER::TEST 
    [symbol] 

TEST names a special variable: 
    Value: 1 
    Documentation: 
    This is a quoted string and it says things 

Un semplice commento nel codice sorgente non consentirà questa forma di integrazione dell'ambiente di sviluppo e di ricerca della documentazione.

4

Ho visto il tuo tag incluso schema e elisp. In CL e Elisp usa sempre docstring. Sono utilizzati dai sistemi di documentazione nelle loro lingue. Scheme non ha questa caratteristica, quindi dovrai continuare a usare i commenti per documentare le funzioni.

+1

Leo: ad esempio in elisp, se usi 'Ch v test RET' per chiedere ad Emacs la tua variabile' test', ti mostrerà la documentazione che hai scritto per esso. Questa è una funzionalità critica per i sistemi di guida integrati e, come dice PuercoPop, dovresti sempre usarla quando definisci le tue funzioni e variabili. Questo vale per * qualsiasi * linguaggio che supporta le stringhe di documentazione come parte della sua sintassi: tu (e chiunque usi il codice) stai invariabilmente meglio se fai uso di tali servizi. – phils