如何善用注释/文档中的代码?

有时候,在文档注释/文档中附一小段代码(当前函数/模块用例,或者某一段配置的前置安装等等),胜过大量文字描述:

测试用例

(defun sum (&rest nums)
"Return the sum of LIST.

>>> (sum 1 2 3)
6"
  (apply '+ nums))

前置安装

;; # Preinstall
;; ```sh
;; brew install foo-server
;; echo 'export PATH=...'
;; ...
;; ```
(use-package foo-package
 ...)

但是在文档/注释中编辑代码是很麻烦的事。可能要先反注释,然后复制到临时 buffer 去编辑,或者要处理引号的转义…等等。

使用这些代码的时候也是面临同样的问题。

有没有 package 可以把注释/文档中的代码提取出来,放到一个新的 buffer 中编辑/运行?

谷歌 “emacs code block in comment” 得到几乎都是不想关结果。就试着自己写,刚刚写完一个提取函数,忽然想起原本应该是要做另一件事的,怎么越跑越偏了,右边无限展开中:(解决 a (解决 b (解决 c (...)))) :sweat_smile:

相关主题:

4 个赞

不同的代码可以有不同的处理方式

当然,也可以用一种统一的形式(我觉得这种更好)

可以与eldoc结合,提取参数,得到参数类型

查询应该够快

我想用lua结合redis,你呢?

我想,首先解决编辑的问题,注释/文档中的代码快可以采用 markdown 的形式。

然后再考虑执行,但是不需要做到像 orgmode src block 那么复杂。

先考虑编辑,你的需求跟 Org Mode 的 C-c ’ (org-edit-src-code) 类似,看你代码块的格式,应该不难实现,Escape 等细节可以先不考,先实现个简单的用段时间看看再说。

有个 edit-indirect 包,可以用一个专门的 Buffer 编辑当前的 Region,我有装但几乎没用过。Markdown 的编辑代码块的功能就是用它实现的。

org-mode是emacs內建的,感覺各方支持都會好一點。

可以考慮用mmm-mode,然後做一個run doctest之類的東西

我目前也是基于 edit-indirect 正在实现的编辑功能

注释/文档还是保持它原本的属性,非编辑状态下不引入额外的 language mode

写个比 edit-indirect 更具体、比 org-edit-src-code 更一般化的工具,一些难以编辑的内容,比如:

  • Org Mode、Markdown 等 Markup 的代码块、链接、图片链接、公式等;
  • 各种编程语言中的 String、正则表达式、注释、Docstring;
  • 还有你举的例子,注释和文档中的代码块。

而且用户自定义支持的格式,比如 Markdown 中的 <kbd>,我希望编辑的时候,直接按键就 OK 了,不用手打。编辑的行为也能扩展,比如插入图片链接时,可以用 MiniBuffer 读取链接和描述。

一个包能覆盖好多包:

  • org-edit-src-code
  • string-edit
  • elisp-docstring-mode
3 个赞

进展

目前实现了:

  1. 注释块(连续多行的注释)编辑

    把整个注释块提取到临时 buffer 编辑,使得可以专心输入内容,不必操心注释符号

    注释块必须是左侧没有代码:

          ;; comment1
          ;; comment2
          ;; comment3
    

    暂不能处理左侧有代码的情况:

    (fn1) ;; comment1
    (fn2) ;; comment2
    (fn3) ;; comment3
    

    因为注释块被提取到另外一个 buffer 编辑的时候,必然出现增加/删除行的情况。如果编辑完成返回,对应关系不好处理。也许需要有个 narrow-to-rectangle 函数把左侧锁定住,我在讨论 关于规律性代码的输入技巧 的时候就开始有打算要实现,起了个头,但没有完成。

    目前的做法是,用正则删除左边的空白(所以必须要求是空白),返回时再补全。

  2. 注释块中的代码块编辑

    把代码提取到指定模式的 buffer 中编辑

    代码块可以由以下形式包裹:

        ```lang
        code
        ```
    

        ,---lang
        | code
        `---
    

    允许添加自定义包裹正则表达式。

  3. {,doc}string 内容编辑

    把 string 内容提取到临时 buffer 编辑,并进行引号转义处理,免去手动输入。

  4. {,doc}string 中的代码块编辑

    类似 2,增加了引号转义处理。

支持的语言:

  • lisp
  • c
  • python/ruby (单引号的 doc string 转义没有实现)

允许自行添加其它语言支持:

(defcustom -comment-regexp-alist
  '((emacs-lisp-mode    . (";+"))
    (c-mode             . ("//+" "\\*+"))
    (c++-mode           . c-mode)
    (python-mode        . ("#+"))
    (ruby-mode          . ("#+")))
  "Alist of comment regexp."
  :group 'commentdown
  :type 'alist)

包名暂定 commentdown,并不是很满意。

3 个赞

整个注释内容直接用orgmode或markdown就好了,这样写注释就有动力了。然后又感觉想要所见即所得功能了,太喜欢typora的体验了

edit-indirect实现应该是正解,符合楼主描述的场景。