[주석] 코드 문서화를 위한 주석 규칙 (@param, @return 활용기)

프로젝트 소스를 보다가 이런 주석이 있다.

	 /**
	 * 요청 결과 상세 조회.
	 *
	 * @param request      the request
	 * @param commonInfo   the common info
	 * @return the req result detail
	 */

여기서 @param, @return은 무엇?

 

@param

변수를 설명할 때 사용하는 어노테이션이다. 즉, 멤버 변수에 주석은 @param을 사용한다.

 

@return

리턴 설명할 때 사용하는 어노테이션이다.

 

그 외에도 여러가지 어노테이션들이 많다.

 

---

주석 작성 comment block

• comment block은 아래와 같이 사용한다

/**
 * @command
 */

• @file
  • 현재 파일 이름을 작성
  • 파일 표시 @file을 작성하지 않으면 문서화 하지 않는다
• @author
  • 작성자 - 작성자가 여러 명일 경우 콤마( , )를 구분자로 작성

/**
 *@author A, B, C
 */

• @brief
  • 파일에 대한 설명을 작성 

/**
 * @brief 설명
 */

• @see
  • 참고사항, 해당 주석 관련 내용을 볼 때 추가적으로 확인해야 할 사항들이 있다면 작성

/**
 * @see 참고사항 작성
 */

• @todo
  • 추가적으로 처리해야 할 사항들은 작성

/**
 * @todo 추가적으로 해야 할 사항
 */

• @deprecated
  • 삭제 예정 표시

/**
 * @deprecated (삭제) 설명
 */

• command 작성 순서
  • @file, @brief, @author, @param, @return, @see, @todo, @deprecated 순서로 작성!
• 자료형 작성 규칙
  • 자료형 타입 bool, int, float, string, array, object 에서 선택적 사용
  • 소문자 사용
  • 여러 형태의 자료형이 표시되어야 할 때는 파이프( | )를 이용

/**
 * @return string | object
 */

• 주석에서 띄어쓰기 방식
  • 주석에서 설명 글이 한줄 이상 작성되어야 할 경우 줄 마지막에 "\n" 입력 후 줄 바꿈한다.

/**
 * @brief 설명 \n
 * 상세설명 상세설명 \n
 * 상세설명1 상세설명1 \n
 */

※ 순서! ( @file -> @brief -> @author -> @see -> @todo -> @deprecated 순으로 사용)

 

참조: https://github.com/xpressengine/xe-core/wiki/%EC%BD%94%EB%93%9C-%EB%AC%B8%EC%84%9C%ED%99%94%EB%A5%BC-%EC%9C%84%ED%95%9C-%EC%A3%BC%EC%84%9D-%EA%B7%9C%EC%B9%99(Draft-v0.1)

xpressengine/xe-core