Text only | Text with Images

newLISP Fan Club

Forum => Anything else we might add? => Topic started by: Dmi on October 01, 2005, 01:04:23 PM

Title: autodocumentation
Post by: Dmi on October 01, 2005, 01:04:23 PM
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?
Title:
Post by: nigelbrown on October 02, 2005, 03:47:02 AM
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
Title:
Post by: Lutz on October 02, 2005, 06:02:34 AM
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
Title:
Post by: Dmi on October 02, 2005, 07:57:56 AM
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.
Title:
Post by: Sammo on October 02, 2005, 01:24:29 PM
Based on work in this forum by Nigel Brown and HPW, the function (doc) has already been written.
Code Select
(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
;; 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.
Title:
Post by: Dmi on October 02, 2005, 01:52:50 PM
very nice! :-)
Title:
Post by: HPW on October 03, 2005, 01:32:38 AM
>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
Title:
Post by: nigelbrown on October 03, 2005, 04:09:25 PM
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
Text only | Text with Images