autodocumentation

[Dmi]

I found that I write new functions as fast as I forget already wrotten ones.
Nevertheless I want to reuse my own code again and again :-)
Does somebody solve that problem?

[nigelbrown]

Perhaps the possibility of a documentation string could be considered (re-visited?)?
In Common Lisp a function can have a string (although from memorythe keeping of that string is implementation dependent) for documentation. Having a documentation slot available in a lambda would aide function reuse at a small? cost.

Nigel

[Lutz]

I always liked (and have used extensively) the Java approach, where you write function headers in a specific format and then process your file with another program (javadoc -> newlisp2doc) to generate HTML documentation. This should be easy to do written in newLISP.

Lutz

[Dmi]

In comlex system we can have many modules placed in files in library directories but not yet loaded into interpreter.
Usually all them will be interesting when possibility search is performed - so javadoc-style may be cool.

Another problem is possibility search itself. Suppose, we want to find some feature. How we will perform search?
Using keywords from description?
Using keywords from description and function code?

Suppose, we already writing some function now... Is there a way to perform it's comparsion by (structure, used functions, parameter names) to functions already present in whole library?
Sounds pretty fantastic, but in other hand we need not exact results - only good approximation...

Either (imho) it would be cool to have a common syntax for writing a (small, laconic) function descriptions.

[Sammo]

Based on work in this forum by Nigel Brown and HPW, the function (doc) has already been written.

Code: Select all

(define (doc f)
    "(doc f) --> display function f's doc string, if present"
    (if (and (or (lambda? f) (macro? f))(string?(nth 1 f)))
        (begin (print(nth 1 f)) (write-line) true)
        nil))

Using the following function as an example:

Code: Select all

;; hex
;; return decimal 'value' as a hex string in a field of 'n' digits
;; e.g., (hex) --> "0x00"
;; e.g., (hex 0) --> "0x00"
;; e.g., (hex 15 4) --> 0x000F"
;;
(define (hex value n)
    "(hex [value [n]]) --> return value (default 0) as hex string in a field of n (default 2) digits"
    (format
        (if (integer? n) (string "0x%0" n "X") "0x%02X")
        (or value 0) ))

then you can use (doc) to retrieve the doc string.

> (doc hex)
(hex [value [n]]) --> return value (default 0) as hex string in a field of n (default 2) digits
true

There is a lengthy thread (which I cannot now find) about this functions and doc strings.

[Dmi]

very nice! :-)

[HPW]

>There is a lengthy thread (which I cannot now find) about this functions and doc strings.

http://www.alh.net/newlisp/phpbb/viewtopic.php?t=378

[nigelbrown]

I thought I felt a sense of deja vu.
Thanks for remembering the thread.

Nigel

PS I've now got the documentation function in my init.lsp