phpDocumentor/ApiGen @author 태그 위치

Question

일반적인 프로그래밍 질문으로 게시하고 싶습니다. 이유는 다른 문서 시스템이 태그를 다르게 처리하기 때문에 특정 언어에 대해 "옳은"또는 "잘못된"내용에 대한 자체 규칙을 적용하기 때문입니다.

이제 해당 언어가 PHP입니다. 현재로서는 "표준"문서화 시스템이 없습니다. phpDocumentor가 있는데, 프로젝트가 구식이되는 것처럼 보입니다. ApiGen과 같은 현재 제품은 구문을 지원하기 위해 노력하는 것 같습니다.

하나의 태그 @author 태그는 어디에 넣을 지 잘 모릅니다. 나는 파일 수준의 문서 블록과 함께 배치하는 느낌. @copyright, @license, @package 및 @link와 함께 대신 클래스 수준의 의사 블록 안에. 일부 컨텍스트의 경우 : PHP 파일에는 각각 하나의 클래스 선언 만 있습니다.

그러나 나는이 사실을 받아 들일만한 표준으로지지하는 증거를 찾지 못했습니다. 실제로 어느 위치를 선호하는지 알 수있는 정보는 거의 없습니다. 그래서 아마도이 정보를 파일 수준의 문서 블록과 클래스 수준의 문서 블록에 모두 포함해야한다고 생각하게되었습니다.

몇 가지 예 : OpenEMR은 파일 수준 블록과 클래스 수준 1() 모두에서 @author를 사용하는 것을 선호합니다. 그러나 ApiGen (교리 ORM의 API에 의해 참조

/** 
* library/sql_upgrade_fx.php Upgrading and patching functions of database. 
* 
* Functions to allow safe database modifications 
* during upgrading and patches. 
* 
* Copyright (C) 2008-2012 Rod Roark <rod@sunsetsystems.com> 
* 
* LICENSE: This program is free software; you can redistribute it and/or 
* modify it under the terms of the GNU General Public License 
* as published by the Free Software Foundation; either version 3 
* of the License, or (at your option) any later version. 
* This program is distributed in the hope that it will be useful, 
* but WITHOUT ANY WARRANTY; without even the implied warranty of 
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
* GNU General Public License for more details. 
* You should have received a copy of the GNU General Public License 
* along with this program. If not, see <http://opensource.org/licenses/gpl-license.php>;. 
* 
* @package OpenEMR 
* @author Rod Roark <rod@sunsetsystems.com> 
* @author Brady Miller <brady@sparmy.com> 
* @link http://www.open-emr.org 
*/ 

/** 
* inline tags demonstration 
* 
* This class generates bars using the main algorithm, which also 
* works heavily with {@link foo()} to rule the world. If I want 
* to use the characters "{@link" in a docblock, I just use "{@}link." If 
* I want the characters "{@*}" I use "{@}*}" 
* 
* @author ahobbit 
* @copyright middleearth.org XVII 
* @version 1.2.3 
*/ 
class bar 
{ 

} 

두 가지 프로젝트 : 문서는이 파일이 클래스가 아니라 다수의 기능을 포함하지 않는 경우에만 동시에 발생하거나하도록 구성되어 있는지 여부를 지정하지 않습니다 및 Nette API)는 파일 수준 doc 블록에서 @author 태그를 사용하지 않고 클래스 수준 doc 블록과 만 사용합니다. 그렇지만 클래스 선언을 포함하여 어디에서 브라우징 할 때 나는 유일한 예제를 보았습니다. 또한 단지를 사용하는 동안,

/** 
* Base contract for ORM queries. Base class for Query and NativeQuery. 
* 
* @license http://www.opensource.org/licenses/lgpl-license.php LGPL 
* @link www.doctrine-project.org 
* @since 2.0 
* @version $Revision$ 
* @author Benjamin Eberlei <kontakt@beberlei.de> 
* @author Guilherme Blanco <guilhermeblanco@hotmail.com> 
* @author Jonathan Wage <jonwage@gmail.com> 
* @author Roman Borschel <roman@code-factory.org> 
* @author Konsta Vesterinen <kvesteri@cc.hut.fi> 
*/ 
abstract class AbstractQuery 
{ ... } 

Nette :

교리는 클래스 수준의 문서 블록 (http://www.doctrine-project.org/api/orm/2.4/source-class-Doctrine.ORM.AbstractQuery.html#AbstractQuery) 안에, 내가 파일 수준의 문서 블록에 배치 생각했을 것이다, 다른 태그와 함께 @author 사용 @author 클래스/인터페이스 맥락에서 태그, 모든 @license의 @copyright 또는 @link를 사용하는 나타나지 않습니다

/** 
* Translator adapter. 
* 
* @author  David Grudl 
*/ 
interface ITranslator 
{...} 

/** 
* Component is the base class for all components. 
* 
* Components are objects implementing IComponent. They has parent component and own name. 
* 
* @author  David Grudl 
* 
* @property-read string $name 
* @property-read IContainer|NULL $parent 
*/ 
abstract class Component extends Nette\Object implements IComponent 
{...} 

Answer 1

당신은 어떤 요소를 문서화하는 데 사용, 그래서 적절한 곳에 사용할 수 있습니다귀하의 필요에 도움이됩니다.

From the manual:

설명

@author 태그에 기록 될 수있는 임의의 요소의 작성자를 기록하는데 사용된다

(전역 변수를 포함한다, 상수 함수를 정의하고, 클래스, 변수, 메소드 , 페이지). phpDocumentor은

꺾쇠 괄호

(< 및>) 사이의 텍스트를 가지고 이메일 주소로 구문 분석하려고합니다. 성공하면 페이지에 mailto 링크가 표시됩니다. 새 v1.2 - @author는 이제 상위 클래스의 하위 클래스에 상속됩니다 (인라인 {@inheritdoc} 참조).클래스가 그 자체로 파일에, 대부분의 시간을, 그래서 파일 및 클래스 저자는 동일합니다

예

/** 
* Page-Level DocBlock example. 
* displays as Gregory Beaver<strong>cellog@php.net</strong> 
* , where underlined text is a "mailto:cellog@php.net" link 
* @author Gregory Beaver <cellog@php.net> 
*/ 
/** 
* function datafunction 
* another contributor authored this function 
* @author Joe Shmoe 
*/ 
function datafunction() 
{ 
... 
} 

편집 명확히한다. 따라서 파일 레벨 블록에는 @author 태그 하나만있을 수 있습니다. 그러나 항상 그런 것은 아닙니다 : 파일이 프로젝트 팀에 의해 자리 표시 자로 자동 생성되었고 다른 작성자가 파일을 구현했거나 파일에 추가 코드가 있습니다. 예를 들어 한 번만 if 문을 사용하면 일부 기능을 정의 할 수 있습니다. t는 이미 존재합니다. 이 경우 파일과 클래스에 서로 다른 @author 태그가 필요할 수 있습니다.

명확성이 염려되거나 자세한 내용을 알아두면 도움이된다고 생각한다면 두 곳 모두에 넣으십시오. 상처받을 수 없다. 개인적으로 @author 태그를 추가하는 경우 모든 중요한 블록 코드 인 모든 파일 및에 태그를 추가 할 것입니다. 이 접근법은 길 아래의 어떤 지점에서 클래스가 인터페이스 또는 추상 클래스로 변환 될 가능성이있는 경우에 의미가 있습니다.

예를 들어, Joe가 만든 클래스 DatabaseConnector이 MySQL 데이터베이스에 연결됩니다. 시간이 지남에 따라 사용자는 PostgreSQL을 더 추상적으로 만들어서 사용자가 PostgreSQL을 사용할 수도 있습니다. 따라서 Bob은 DatabaseConnector을 추상 클래스로 바꾸고 조의 원래 코드는 DatabaseConnectorMySQL이라는 새 클래스의 일부가됩니다. Joe는 여전히 DatabaseConnector.php가 @author이고 모든 코드가 DatabaseConnectorMySQL이지만 Bob은 현재 DatabaseConnector에있는 코드를 모두 작성했습니다. 그래서, 신용을 제공 할 때나, 질문이있는 경우 누구에게 연락해야 하는지를 말하면서, 누가 썼는지, 누가 어떤 선택을 할 책임이 있는지 (예 : 메소드 이름) 표시하고 싶습니다.

어쩌면 당신은 너무 많은 것 같아서 혼란을 불러 일으킬 것입니다. 그리고 당신은 오히려 단지 다른 곳에있는 역사를 설명 할 것입니다. 또는 필요한 정보가 모두 버전 관리 리포지토리 (예 : git blame)에 저장되었으므로 @author 태그에 전혀 신경 쓰지 않아도됩니다. 그것은 당신에게 달렸습니다. 여기에는 잘못된 대답이 없습니다.