우리가 여러 위젯들을 사용할 때 무조건 한 번씩 보는 게 있다. 바로 그 위젯에 대한 툴팁, 문서 팝업이다. 주로 그 코드에 마우스를 올리거나 Android Studio에서는 Ctrl + Q, VSCode에서는 Ctrl + K로 확인 가능한 팝업 창인데
이 문서툴(Documentation tool)을 우리는 꼭 확인해야지만 위젯을 쉽고 완벽하게 사용할 수 있다.
당연한 거지만 그 위젯의 타입과 파라미터, 설명과 함께 종종 예제 코드도 포함되어 있기 때문으로 그것을 보고 코드를 작성하면 처음 써본 위젯이라도 편하게 쓸 수 있다.
그렇다면 이 위젯을 이 문서툴만 확인한 것이 아니라 직접 이 위젯이 정의되어 있는 파일(Go to Definition)로 들어가 본 적이 있는가?
Android Studio에서는 Ctrl + Click,Ctrl + B, 마우스 휠로 이동이 가능하고 VSCode에서는 Ctrl + Click, F12로 이동이 가능하다.
이 디피니션 파일을 보면 문서툴에서 표시되어 있는 힌트들이 어떻게 적혀 있는지 확인할 수 있는데 이번에는 한번 그 작성법을 알아볼 것이다.
진-득하게 알아보고 싶다면 이 공식 문서를 한번 훑어보는 것을 추천한다.
https://dart.dev/effective-dart/documentation
Effective Dart: Documentation
Clear, helpful comments and documentation.
dart.dev
예전 코드같은 것을 다시 보다 보면 본인이 작성한 코드라도 기억이 나지 않을 때가 있다. 이런 상황을 방지하게 위해서라도 우리는 보통 주석을 쳐서 그 코드에 대한 설명을 해 놓는다. 그렇다면 여기에서 더 나아가서 코드 작성 중에 어떠한 메서드를 사용할 때에 바로 문서툴을 띄우면 힌트가 나오도록 하려고 하면 어떻게 해야 할까? 바로 Doc comments 기능 사용하면 된다.
기본적으로 JSDoc 과 같이 ///를 사용해서 작성하면 된다.
int _add(int a, int b) {
return a + b;
}이런 간단한 메서드를 작성했다고 가정한다. 솔직히 이런 코드에는 주석도 민망하긴 한데 암튼 여따가 주석을 쳐보자. 현재 이 상태에서 이 메서드의 문서툴을 불러오면 아래와 같이 보인다.
기본적으로 나타나고 있는 설명들은 이런 것들을 나타내준다.
1. package:untitled3/main.dart
- 이 메서드가 정의된 파일의 위치
- main.dart 파일 안에 있다는 것을 알 수 있음
2. int _add(int a, int b)
- 함수의 시그니처(signature)로 함수의 이름, 매개변수 타입, 반환 타입 등등
- 이건 int 타입을 반환하고, int a, int b 두 개의 정수를 인자로 받는 _add라는 프라이빗 함수라는 것을 알 수 있음
3. Containing class: Test
- 이 함수 _add가 포함된 클래스 이름이 Test라는 것
- 즉, _add는 Test 클래스 안에 정의된 인스턴스 메서드 or static 메서드라는 걸 알 수 있음
4. Type: int Function(int, int)
- 이건 _add라는 함수의 타입 정보
- 즉, 이 함수는 (int, int)을 받아서 int를 반환하는 함수 타입(Function type)이라는 뜻
이게 기본적으로 주는 정보인 것을 알았는가? 그렇다면 이제 진짜로 작성해 보자.
기본적으로 작성 방법은 마크다운 스타일로 작성된다.
/// 두 개의 정수를 더합니다.
///
/// [a] 첫 번째 정수
/// [b] 두 번째 정수
///
/// 반환값: 두 수의 합
int _add(int a, int b) {
return a + b;
}
/// 를 사용하여 주석을 작성하면 된다. /** */도 지원이 되긴 하는데 바꾸라고 핀잔준다.
앞서 말했듯이 마크 다운 문법도 지원하기 때문에 넣고 굵게 하고 싶다면 **굵게**를, 기울기를 넣고 싶다면 *기울임*을 사용해 주면 된다. 또한 링크를 삽입하고 싶다면 [링크](url) 형식으로 사용해 주면 된다.
또한 [변수명] 이렇게 사용해 주면 툴팁에서는 해당 변수/파라미터에 대한 링크처럼 표시된다. 이렇게 되면 함수나 클래스 내부에서 선언된 이름과 연결되면 자동 하이라이팅된다.
/// 두 개의 정수를 더합니다.
///
/// [a] **첫 번째 정수**
/// [b] *두 번째 정수*
///
/// 반환값: 두 수의 합
/// [블로그](https://ch5c.tistory.com/)
int _add(int a, int b) {
return a + b;
}
지금 코드를 보면 계속 메서드 위에다가 주석을 위치시키고 있는데 이렇게 하지 않으면 표시가 되지 않으니 무조건 자신이 힌트를 주고 싶은 코드 위에다가 작성해줘야 한다.
또한 안에서 코드 박스 스타일로 보여주고 싶다면 `코드` 형식을 사용해 주면 된다. [변수명] 형식과 비슷하지만 이건 그냥 코드 블록처럼 보이는 기능밖에 없다.
/// 두 개의 정수를 더합니다.
///
/// [a] **첫 번째 정수**
/// [b] *두 번째 정수*
///
/// `반환값`: 두 수의 합
/// [블로그](https://ch5c.tistory.com/)
int _add(int a, int b) {
return a + b;
}
또한 목록 형식(순서 X, 순서 O)으로도 보여줄 수 있는데 시작 부분에 - 혹은 1. 을 넣어주면 된다.
/// 두 개의 정수를 더합니다.
///
/// - [a] **첫 번째 정수**
/// - [b] *두 번째 정수*
///
/// 1. `반환값`: 두 수의 합
/// 2. [블로그](https://ch5c.tistory.com/)
int _add(int a, int b) {
return a + b;
}
마지막으로 코드 예제를 표시해야 할 때에는 ```코드``` 형식(마크다운 블록 코드)을 사용해 주면 된다.
이건 살짝 다른데 처음 ``` 을 사용한 후에 사용하는 언어를 적어줘야지 VSCode 같은 데에서도 문법 하이라이팅이 잘 되게 된다. 그리고 코드 블록이기 때문에 당연히 줄 넘김은 가능하다.
/// 두 개의 정수를 더합니다.
///
/// - [a] **첫 번째 정수**
/// - [b] *두 번째 정수*
///
/// ```dart
/// onTap: () {
/// _add(1, 2);
/// },
/// ```
/// 1. `반환값`: 두 수의 합
/// 2. [블로그](https://ch5c.tistory.com/)
int _add(int a, int b) {
return a + b;
}
이렇게 문서 주석(Doc comments)을 달아보았는데 보통 사용하는 곳은 협업 프로젝트같이 큼지막한 곳에서 사용되기 때문에 일반적으로 공부하는 입장에서는 솔직히 거의 쓸 일이 없긴 하다. 하지만 자기가 레전드급 메서드를 만들었다 해서 그걸 꼭 설명을 해줘야만 알아들을 수 있는 그런 거라면 이렇게 문서 주석을 달아놓아 추후에 사용이 편하도록 하자. 암튼 도움이 되었길 바라며 마치겠다.
