Flutter - [dartdoc] API 자동 문서화

안녕하세요? Flutter로 라이브러리를 개발할 때 코드상에 주석을 자동을 문서화하는 방법을 한 번 알아보겠습니다.
doxygen과 비슷한 기능이라고 생각하시면 될 것 같습니다.

그럼 먼저 주석을 달아봅시다.

/ 3개로 주석을 메소드나 클래스 정의 위에 달게되면 dartdoc으로 자동으로 문서화할 수 있습니다.

아래 category의 경우 dartdoc_options.yaml을 통해서 정의할 수 있는데 반드시 설정해야 하는 부분은 아니기에 넘어가도록 하겠습니다.

/// {@category Basics}
/// {@category Assets, Images, and Icons}
/// {@subCategory Information displays}
/// {@image <image alt='' src='/images/catalog-widget-placeholder.png'>}
class Icon extends StatelessWidget {}

주석 가이드는 아래를 참고합니다.

https://dart.dev/guides/language/effective-dart/documentation

dartdoc 설치하기

dartdoc을 사용하기 위해 dartdoc을 설치합니다.

$ flutter pub global activate dartdoc
or
$ dart pub global activate dartdoc

doc 생성하기

아래 커맨드를 flutter project의 root에서 실행합니다.

$ flutter pub global run dartdoc
or
$ dart pub global run dartdoc

결과 확인하기

프로젝트 폴더 루트에 doc 폴더가 생성되어 있는 것을 확인할 수 있습니다. 그 안에 index.html을 찾아 결과를 확인합니다.

$ cd doc/api
# index.html을 열어서 결과를 확인합니다.

추가적인 설정을 하고싶으시면 아래 문서를 참고하셔서 dartdoc_options.yaml를 작성해보시길 바랍니다

아래는 dartdoc_options.yaml 예제입니다.

dartdoc:
  categories:
    "First Category":
      markdown: doc/First.md
      name: Awesome
    "Second Category":
      markdown: doc/Second.md
      name: Great
  categoryOrder: ["First Category", "Second Category"]
  examplePathPrefix: 'subdir/with/examples'
  includeExternal: ['bin/unusually_located_library.dart']
  nodoc: ['lib/sekret/*.dart']
  linkTo:
    url: "https://my.dartdocumentationsite.org/dev/%v%"
  showUndocumentedCategories: true
  ignore:
    - ambiguous-doc-reference
  errors:
    - unresolved-doc-reference
  warnings:
    - tool-error

참조

https://github.com/dart-lang/dartdoc