Re: hyperdoc and hyperdocumentation in ASDF

Gary King wrote:
> Hi Robert,
> 
> I'm not against removing them but I'm curious as to what the  
> motivation is for doing so.

I don't like to see dead code, and I especially don't like to see dead
code that's exported as a part of the interface, and that doesn't have
documentation.

I generally think of this as a kind of user interface issue.  The user,
even if a programmer, shouldn't have to guess what parts of the
interface work and what don't.  And it wastes time for everyone because
busted parts of the code will be rediscovered, analyzed and explained away.

Note also that this code ships in binary form with lisps like ACL and
SBCL.  That means that not only will hyperdoc not work, a user will have
to seek out the sources to find out why it doesn't work.  They might
just try to call hyperdoc, and then start frittering away time, trying
to figure out the right argument signature.

I'm further convinced that this stuff should be thrown away because it's
undocumented.  There's no

;;; this is the stub for a hyperdoc interface I'd like to see someday

or anything.

If it were documented, it might serve as a useful stub for someone to
fill in someday.  As it stands, there's not even a clue to the reader
about the original intent.

As a fall-back position, if it REALLY gives someone heartburn to excise
this, we could simply remove the two symbols from the exported list.
That's what really bugs me --- we are advertising an interface that we
know to be busted...

Here's the proposed patch (also as an attachment, because I fear what
thunderbird's wrapping will do to this):

Index: asdf.lisp
===================================================================
RCS file: /cvsroot/cclan/asdf/asdf.lisp,v
retrieving revision 1.115
diff -b -u -F^(def -r1.115 asdf.lisp
--- asdf.lisp   15 Feb 2008 12:14:48 -0000      1.115
+++ asdf.lisp   9 Apr 2008 15:17:03 -0000
@@ -40,7 +40,6 @@
 (defpackage #:asdf
   (:export #:defsystem #:oos #:operate #:find-system #:run-shell-command
            #:system-definition-pathname #:find-component ; miscellaneous
-           #:hyperdocumentation #:hyperdoc

            #:compile-op #:load-op #:load-source-op #:test-system-version
            #:test-op
@@ -1241,12 +1240,6 @@ (defun run-shell-command (control-string
     ))


-(defgeneric hyperdocumentation (package name doc-type))
-(defmethod hyperdocumentation ((package symbol) name doc-type)
-  (hyperdocumentation (find-package package) name doc-type))
-
-(defun hyperdoc (name doc-type)
-  (hyperdocumentation (symbol-package name) name doc-type))

 (defun system-source-file (system-name)
   (let ((system (asdf:find-system system-name)))

-------------------------------------------------------------------------
This SF.net email is sponsored by the 2008 JavaOne(SM) Conference 
Don't miss this year's exciting event. There's still time to save $100. 
Use priority code J8TL2D2. 
http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone

_______________________________________________
cclan-list mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/cclan-list

Index: asdf.lisp
===================================================================
RCS file: /cvsroot/cclan/asdf/asdf.lisp,v
retrieving revision 1.115
diff -b -u -F^(def -r1.115 asdf.lisp
--- asdf.lisp	15 Feb 2008 12:14:48 -0000	1.115
+++ asdf.lisp	9 Apr 2008 15:19:24 -0000
@@ -40,7 +40,6 @@
 (defpackage #:asdf
   (:export #:defsystem #:oos #:operate #:find-system #:run-shell-command
            #:system-definition-pathname #:find-component ; miscellaneous
-           #:hyperdocumentation #:hyperdoc
 
            #:compile-op #:load-op #:load-source-op #:test-system-version
            #:test-op
@@ -1241,12 +1240,6 @@ (defun run-shell-command (control-string
     ))
 
 
-(defgeneric hyperdocumentation (package name doc-type))
-(defmethod hyperdocumentation ((package symbol) name doc-type)
-  (hyperdocumentation (find-package package) name doc-type))
-
-(defun hyperdoc (name doc-type)
-  (hyperdocumentation (symbol-package name) name doc-type))
 
 (defun system-source-file (system-name)
   (let ((system (asdf:find-system system-name)))