代码注释 – Quarto

Quarto 1.3 新功能

这篇文章是系列文章的一部分，重点介绍 Quarto 1.3 版本中的新功能。获取最新版本请访问下载页面

Quarto 中的代码块和可执行代码单元现在可以包含基于行的注释。基于行的注释提供了一种类似于脚注的方式，将解释附加到代码行上。

例如，以下代码使用注释以通俗语言描述了 R dplyr 管道中的步骤：

library(tidyverse)
library(palmerpenguins)
1penguins |>
2  mutate(
    bill_ratio = bill_depth_mm / bill_length_mm,
    bill_area  = bill_depth_mm * bill_length_mm
  )

1: 取 penguins，然后，
2: 为喙的比例和喙的面积添加新列。

默认的 HTML 注释样式在代码块下方以列表形式显示注释。点击列表中的注释编号会高亮显示代码中相应的行。其他 HTML 样式会隐藏注释，当用户悬停或选择标记时，注释会以工具提示的形式显示。

PDF 格式也支持注释、编号，并在代码下方显示注释文本。在其他格式（如 Word 和 GitHub Markdown）中，注释会标记出注释文本所适用的代码行（或多行代码）。

PDF
GitHub Flavored Markdown

PDF 格式输出的截图，显示代码注释。

``` r
library(tidyverse)
library(palmerpenguins)
penguins |>
  mutate(
    bill_ratio = bill_depth_mm / bill_length_mm,
    bill_area  = bill_depth_mm * bill_length_mm
  )
```

第 3 行  
取 `penguins`，然后，

第 4-7 行  
为喙的比例和喙的面积添加新列。

要为代码块添加代码注释，您需要添加两项内容：在代码单元格中添加特殊格式的代码注释，以及在代码单元格下方添加有序列表，包含注释文本：

代码注释：代码单元格中每个带注释的行应以注释（使用代码单元格语言的注释字符）结尾，后跟一个空格，然后是括在尖括号中的注释编号（例如 # <2>）。如果注释跨越多行，可以重复使用相同的注释编号。
有序列表：有序列表应紧跟在代码单元格之后，并包含每个注释的内容。有序列表中的每个编号项将对应于代码中具有相同注释编号的行（或多行）。

例如，上面的注释是通过在 Quarto 文档中包含以下内容生成的：

```r
library(tidyverse)
library(palmerpenguins)
penguins |>                                      # <1>
  mutate(                                        # <2>
    bill_ratio = bill_depth_mm / bill_length_mm, # <2>
    bill_area  = bill_depth_mm * bill_length_mm  # <2>
  )                                              # <2>
```
1. 取 `penguins`，然后，
2. 为喙的比例和喙的面积添加新列。

您可以在预发布亮点的代码注释页面上阅读更多关于如何控制注释样式以及注释是否显示的信息。