---

6.1.1 Domesticity ¶

Domesticity is the concept defining what “belongs” to the library. It ultimately affects what can appear in the reference manual, and what cannot.

The basic rule is that anything defined in one of the library’s source files is domestic, and the rest is foreign. If for some reason, the source file is unknown, then, the definition will be considered domestic if the symbol naming it is from a domestic package.

This view on domesticity has implications on what is documented, which are worth mentioning.

• Language extensions (for example, new methods on standard generic functions) and, in general, new local definitions on symbols from foreign packages are considered domestic, and hence will appear in the reference manual.
• Conversely, extensions to the library, but defined outside of it, will not be part of the resulting reference manual, as they will be considered foreign.

Note that even though they are not normally meant to appear in the final reference manual, Declt may be led to create foreign definitions (sometimes a lot of them) as well as domestic ones. For example, if your library adds a method to make-instance, Declt will internally create a (foreign) definition for the make-instance generic function. Foreign definitions are never complete however (otherwise, we would end up with a complete documentation for the whole Lisp image): only the information relevant to the library is kept around.

As said before, it is possible to include those (partial) foreign definitions in the documentation by using the :foreign-definitions option to declt or assemble. Continuing with the previous example, local methods on make-instance normally appear as toplevel, standalone definitions in the documentation, as they belong to a foreign generic function. If, however, foreign definitions are included in the documentation, there will be a toplevel (partial) entry for make-instance, and the domestic methods will appear inside it (truly foreign methods will never be documented).