如何编写 Emacs Lisp 文档字符串
当语言将文档字符串作为核心特性时,这通常意味着语言运行时本身就具备访问或修改文档字符串的能力。这使得自省 (Introspection) 变得非常直接:通过在运行时动态地获取和显示文档,可以非常方便地构建帮助系统。 从语言设计者的角度来看,支持文档字符串意味着文档不是代码的附属品,而是和代码本身一样重要,它和函数名、参数、返回值以及函数体一样,都是构成完整代码单元的关键信息。它表明语言的设计者将可读性、可维护性和协作性放在了非常重要的位置,并将文档视为实现这些目标的关键手段。 在版本控制系的管理下,开发者更新函数通常也会更新其文档字符串,这保证了代码和文档的一致性。这在短期来看确实会增加工作量,但这笔「额外」的投入,从长远来看,对程序的可维护性来说是巨大的收益。清晰准确的文档能够起到降低认知负荷、帮助定位问题,以及促进协作的作用。 也许你和我一样,在学 Python 时第一次了解到文档字符串这个概念。直接支持文档字符串的程序语言不止 Python 一家,下面我会介绍一些(出于显而易见的原因,我没有提到一众 Lisp 语言,比如 Common Lisp)。 就像上面提到的那样,Emacs Lisp 文档的附录 D.6 总结了一些编写 docstring…