Package documentation problem.
Robin Lee Powell
I'll be seeing about trying to fix this, but I wanted to put it out
there in case other people have ideas.
Weblocks has this:
(without-package-variance-warnings
(defpackage #:weblocks
The macro is:
(defmacro without-package-variance-warnings (&body body)
`(eval-when (:compile-toplevel :load-toplevel :execute)
(handler-bind (#+sbcl(sb-int:package-at-variance #'muffle-warning))
,@body)))
Because of this, mudballs doesn't see the defpackage, which means no
weblocks-package.html gets created, which kind of kills the
documentation dead.
Suggestions on how to handle this?
-Robin
--
They say: "The first AIs will be built by the military as weapons."
And I'm thinking: "Does it even occur to you to try for something
other than the default outcome?" See http://shrunklink.com/cdiz
http://www.digitalkingdom.org/~rlpowell/ *** http://www.lojban.org/
Leslie P. Polzer
> Because of this, mudballs doesn't see the defpackage, which means no
> weblocks-package.html gets created, which kind of kills the
> documentation dead.
>
> Suggestions on how to handle this?
Yes, I think Mudballs should be fixed to allow non-toplevel defpackage
forms.
Sean Ross
Yes, this is a rather severe shortcoming of the documentation action I
will raise an issue to address this.
sean.
Robin Lee Powell
Thus far still failing to understand document-action, I wonder if a
solution to this and other issues I've hit (such as "defwidget", a
macro for "defclass", not being dealt with properly) is to
macroexpand things before deciding what they are?
Robin Lee Powell
>
> On Mon, Apr 27, 2009 at 10:10:07AM +0100, Sean Ross wrote:
> >
> >
> > On 26 Apr 2009, at 09:10, Leslie P. Polzer wrote:
> >
> > >
> > >
> > >> Because of this, mudballs doesn't see the defpackage, which
> > >> means no weblocks-package.html gets created, which kind of
> > >> kills the documentation dead.
> > >>
> > >> Suggestions on how to handle this?
> > >
> > > Yes, I think Mudballs should be fixed to allow non-toplevel
> > > defpackage forms.
> >
> > Yes, this is a rather severe shortcoming of the documentation
> > action I will raise an issue to address this.
>
> Thus far still failing to understand document-action, I wonder if
> a solution to this and other issues I've hit (such as "defwidget",
> a macro for "defclass", not being dealt with properly) is to
> macroexpand things before deciding what they are?
Here's a patch to do just that. This fixes all the "not digging
deep enough" problems I've had with mudballs against weblocks so
far. I'm sure it's not the best solution.
-Robin
diff -u -r 0.1.11-orig/action.lisp 0.1.11/action.lisp
--- 0.1.11-orig/action.lisp 2009-04-26 10:35:03.000000000 -0700
+++ 0.1.11/action.lisp 2009-04-27 21:12:07.000000000 -0700
@@ -372,7 +372,10 @@
(handler-bind ((condition (lambda (c) (when-let (restart (find-restart 'continue c))
(invoke-restart restart)))))
(do-forms (form file)
- (process-form form))
+ (cond
+ ((doc-type-processor form) (process-form form))
+ ((doc-type-processor (macroexpand-1 form)) (process-form (macroexpand-1 form)))
+ (t (process-form (macroexpand form)))))
*collector*)))
@@ -428,6 +431,7 @@
(mapcar 'process-form forms))))
(define-toplevel-form eval-when 'cddr)
+(define-toplevel-form handler-bind 'cddr)
(define-toplevel-form progn 'cdr)
;; macro expansions should be toplevel forms too
;; add macrolet & symbol-macrolet.
Leslie P. Polzer
> + ((doc-type-processor form) (process-form form))
> + ((doc-type-processor (macroexpand-1 form)) (process-form (macroexpand-1
> form)))
> + (t (process-form (macroexpand form)))))
The calls to MACROEXPAND(-1) should be eventually replaced
by calls to an implementation of MACROEXPAND-ALL.
Leslie
Sean Ross
Yes, or a tree walker is required in order to do this properly.
Unfortunately documenting systems is a tricky process as it's not
clear what the packages to document should be.
Macroexpanding is a definitely a good thing, and I will apply the
patch, but I think some sort of addition to the doc-hints
section would be useful for cases where document-action isn't picking
up the packages to document.
Of course this wouldn't be an issue if the we distributed packages
instead of systems...........
- sean
Leslie P. Polzer
> Yes, or a tree walker is required in order to do this properly.
I originally meant to state this but then I had noticed that it
might be alright to do pretty superficial analysis as it is done
at compile time; e.g. only honoring DEFPACKAGE forms
when they are at the top-level (or one level below a HANDER-BIND,
PROGN, EVAL-WHEN, ... as these are exceptions).
> Macroexpanding is a definitely a good thing, and I will apply the
> patch, but I think some sort of addition to the doc-hints
> section would be useful for cases where document-action isn't picking
> up the packages to document.
Sean Ross
On 28 Apr 2009, at 15:01, Leslie P. Polzer wrote:
>
>
>> Yes, or a tree walker is required in order to do this properly.
>
> But is it really?
>
> I originally meant to state this but then I had noticed that it
> might be alright to do pretty superficial analysis as it is done
> at compile time; e.g. only honoring DEFPACKAGE forms
> when they are at the top-level (or one level below a HANDER-BIND,
> PROGN, EVAL-WHEN, ... as these are exceptions).
>
No, not really :)
I think that the superficial approach, coupled with a way to override
the behaviour is the best way forward for the moment.
- sean