如何善用注释／文档中的代码？

Emacs-general
1

有时候，在文档注释／文档中附一小段代码（当前函数／模块用例，或者某一段配置的前置安装等等），胜过大量文字描述：

测试用例

(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 个赞
2

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

当然，也可以用一种统一的形式（我觉得这种更好）

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

查询应该够快

我想用lua结合redis，你呢？

3

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

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

4

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

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

5

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

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

6

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

7

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

8

写个比 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 个赞
9

进展

目前实现了：

  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 个赞
10

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

11

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