Are restarts part of a function's "public interface"? in Common Lisp?

Question

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.

Awlwort

nhplace.com/kent/Papers/Exceptional-Situations-1990.html – Cf

cs.cmu.edu/Groups/AI/html/cltl/clm/… – Cf

The question is interesting, but you may want to come up with an example to make clear what you are asking. – Cf

It's a general question about how the existence of restarts should be recorded and communicated. Should restarts be part of a function's contract? – Awlwort

Does the caller see the restart? Usually not. If he provides handlers, then they see the restart - when they are actually called. The handler can query what restarts are available in that case. For interactive handling, they are discoverable. The condition system can be used in different ways. Without knowing how you are using it, it's difficult what you want to document and where. – Cf

When using you would like to bind handlers on condition to choose the restarts that is best suited to the use and I cannot see why the conditions and handlers are not to be documented if there is a possibility the condition will happen and leaked out of the function (not handled internally). – Gap

Answer 1

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).

Copolymer

Yeah, I would think that if a function provides a restart, it would want to make this clear to potential callers that may want to invoke that restart. – Awlwort

@TianxiangXiong Yes, and that's the important part there: whether it's something that a user is intended to (possibly) use. If it is, then it's part of the public API; if it's not, then it's not. – Crick