코드 문서화를 위한 주석 규칙(Draft v0.1)

Draft 문서 입니다. 작성된 사항은 별경될 수 있음을 알려듭니다.

Doxygen을 이용해서 XE를 문서화 하기 위한 주석 규칙을 설명합니다.

##개요

XE는 코드 문서화 도구로 Doxygen을 사용합니다.
Doxygen 에서 제공하는 다양한 주석 작성 방식과 command 종류에 의한 혼란을 방지하고자 아래와 같이 작성 방식을 제한합니다.

#주석 작성 규칙

모든 주석은 영문으로 작성합니다.

주석 작성 comment block

• comment block은 아래와 같이 사용합니다.

  
   	/**
   	 * @command
   	 */
  

주석 command

아래 command 리스트에 명시되지 않은 모든 command는 삭제합니다.
@package, @version, @date 등 아래 설명되지 않는 command는 삭제합니다.

• @file
  파일 표시
  Doxygen은 @file을 작성하지 않으면 문서화 하지 않는다.

  
   	/**
   	 * @file FileNme
   	 */
  

• @author
  작성자

  
   	/**
   	 * @author NAVER ([email protected])
   	 */
  

  작성자가 여러 명일 경우 콤마(,)를 구분자로 작성

  
   	/**
   	 * @author NAVER ([email protected]), XE, XEHUB
   	 */
  

• @brief
  설명

  
   	/**
   	 * @brief 설명
   	 */
  

• @param
  변수 설명

  
   	/**
   	 * @param 자료형 $변수명 설명
   	 */
  

• @return
  리턴 설명

  
   	/**
   	 * @return 자료형 설명
   	 */
  

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

  
   	/**
   	 * @see 참고해야 할 사항을 작성. 
   	 */
  

  ex) class DB의 queryExecute() 를 참고 할 경우 아래와 같이 작성합니다.

  
   	/**
   	 * @see DB::queryExecute()
   	 */
  

• @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
   	 * 상세설명 상세설명 \n
   	 */
  

##작성예시

상단,하단 주석 예시

• 주석방식

   	<?php
   	/* Copyright (C) NAVER <http://www.navercorp.com> */
   
   	/**
   	 * @file addon.controller.php
   	 * @brief Addon module's controller class \n
   	 * @author NAVER ([email protected])
   	 */
   	class addonController extends addon
   	{
   		....중략....
   	}

• 변경 사항

  1. @file, @brief 추가

     • @file 에는 현재 파일 이름을 작성
     • @brief는 파일에 대한 설명을 작성
     • @file, @brief, @author 순서로 작성
     • @file, @brief, @autor, @see, @todo, @deprecated 사용

  2. 파일 하단 주석 제거

     • 파일 하단에 작성하던 End of file, Location 주석을 삭제 합니다.

####class 멤버 메소드, 변수 주석 예시

• 주석 방식

   	<?php
   	....중략....
   	class documentItem extends Object
   	{
   		/**
   		 * @param int $document_srl Document number
   		 */
   		var $document_srl = 0;
   
   		....중략....
   
   		/**
   		 * @brief Constructor
   		 * @param int $document_srl
   		 * @param bool $load_extra_vars
   		 * @param array $columnList
   		 * @return void
   		 */
   		function documentItem($document_srl = 0, $load_extra_vars = true, $columnList = array())
   		{
   			....중략....
   		}
  
   	....중략....
       }

• 변경 사항

  1. 멤버 변수에 주석은 @param 사용

     • @param 작성 방식을 따름
     • @param, @see, @todo, @deprecated 사용

  2. 멤버 메소드에서 @brief 사용

     • @brief, @param, @return, @see, @todo, @deprecated 사용

오류

• 문서화된 결과 중애서 아래 링크는 오류가 발생했으며 해결점을 찾지 못했습니다.
  • config/func.inc.php
  • config/config.inc.php