[editor-hints-devel] My thoughts about markup and docstrings

[David Lichteblau]

Quoting Luis Oliveira (luismbo at gmail.com):
> To cater to option (2), perhaps the ANNOTATE-DOCUMENTATION macro could
> delegate its work when the PARSE-DOCSTRINGS system is pre-loaded?

Sounds clever.  The only danger I see is that the macro will behave
differently in the user's environment than for the author of code that
is being documented.

Would the macro signal errors on invalid docstrings?  Warnings?  Style
warnings?  Signal errors in the parser but then catch and resignal them
as style warnings?

As a package author, I might not have seen these errors before making a
release, because parse-docstrings wouldn't be loaded in my environment
before I'm genering my documentation (and perhaps the symbol in question
isn't being included in my documentation anyway, so I'm not getting the
error at all).

Some of my users might have parse-docstrings loaded, however, and they
would get errors.  In the case of warnings, users with SBCL would still
complain (perhaps I'm actually using parse-docstrings, but ASDF on my
Lisp ignores warnings).  Catching and suppressing the errors might work.
(Users with a weird *break-on-signals* would be still affected, but
perhaps that falls under "then don't do that".)


How about issues with API compatibility though?  We would try to keep
the macro's arguments compatible between versions, but what if we happen
to change them after all?  We wouldn't be able to catch that kind of
error in the same way as parser errors.


d.