I've been trying to understand proper use of restarts and handlers in Common Lisp by reading Peter Seibel's Beyond Exception Handling: Conditions and Restart chapter of Practical Common Lisp, Kent Pitman's Conditional Handling in the Lisp Language Family, as well as some other references.
From what I understand about restarts, they are options provided by a function to its callers to choose the function's behavior when some condition is encountered.
Should it be the case, then, that restarts are treated as part of a function's "public interface", and be documented accordingly?
After all, callers have to know about the restarts and what they do in order to invoke them, right? And it would be a bad thing to get rid of a restart that a caller could be invoking, I presume.
Restarts are named by symbols. If such a symbol is exported from a package, I'd see it as part of the public API, otherwise not. I'd expect all exported symbols to be documented at the appropriate places (docstrings).