코드 문서화를 위한 주석 규칙(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