코드 주석

개요

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 스타일은 주석을 숨긴 뒤 마커를 가리키거나 선택할 때 툴팁으로 표시합니다(아래 Revealjs 예시 참고).

format: revealjs

PDF 포맷 역시 주석 번호와 주석 텍스트를 코드 아래에 표시합니다. Word나 GitHub Markdown 같은 포맷에서는 주석이 적용되는 코드 줄 번호를 함께 표시합니다.

Screenshot of output in PDF format showing code annotation.

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

Line 3  
`penguins` 데이터를 가져온 뒤,

Lines 4-7  
부리 비율과 부리 면적 컬럼을 추가합니다.

코드 블록에 주석을 추가하려면 두 가지가 필요합니다. 코드 셀의 각 줄 끝에 특수 주석을 달고, 코드 셀 아래에 주석 내용을 담은 정렬 목록을 추가합니다. 자세한 문법은 주석 문법을 참고하세요.

code-annotations 옵션은 HTML에서 주석을 어떻게 표시할지(below, hover, select)와 모든 포맷에서 주석을 비활성화할지(false), 완전히 제거할지(none)를 제어합니다.

주석 문법

코드 셀 주석은 다음 두 요소로 구성됩니다.

주석이 달린 각 줄 끝에 공백과 함께 꺾쇠 괄호로 감싼 번호(예: # <2>)를 붙입니다. 여러 줄에 걸치는 주석이라면 번호를 반복해도 됩니다.
코드 셀 바로 아래에 번호 목록을 만들어 각 주석 내용을 작성합니다. 목록의 번호는 코드 줄에 붙인 번호와 일치해야 합니다.

예를 들어 앞서 살펴본 예제 주석은 다음과 같이 작성했습니다.

```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. 부리 비율과 부리 면적 컬럼을 추가합니다.

주석 스타일

HTML 출력에서는 code-annotations 문서 옵션으로 세 가지 주석 스타일을 선택할 수 있습니다.

below: 기본값(code-annotations: below)으로, 주석 텍스트가 코드 셀 아래 나타납니다.
hover: 주석 마커 위에 마우스를 올리면 주석 텍스트가 표시됩니다.
select: 주석 마커를 클릭했을 때 주석 텍스트가 표시되며, 다시 클릭하면 닫힙니다.

예를 들어 hover 스타일을 사용하려면 전체 Quarto 문서는 다음과 같습니다.

---
code-annotations: hover
---

```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. 부리 비율과 부리 면적 컬럼을 추가합니다.

라인 강조 색상은 코드 주석 Sass 변수를 사용해 커스텀 테마에서 제어할 수 있습니다.

주석 제거

특정 포맷에서는 주석을 출력하지 않고 싶을 수 있습니다. code-annotations: none을 설정하면 코드의 주석 마커를 제거하고 주석 텍스트 목록도 생성하지 않습니다.

주석 비활성화

문서에 code-annotations: false를 지정하면 주석 처리를 중단하고, 코드(주석 포함)와 기존 정렬 목록을 그대로 유지합니다.