Java 문서 - @return 및 @param - 우수한 라이브러리

@return 및 @param을 사용하여 코드를 문서화하는 방법을 궁금합니다 ...? 나는 내가 비슷한 것을 할 것이라고 짐작한다.Java 문서 - @return 및 @param

@return(whatever the method is returning) 
@param(parameters that the method is taking in)

나는 나중에 더 많은 설명을 넣어야 할까? 또한, 너무 많은 문서로 뭔가가 있습니까?

출처

2014-03-13 allyhalcyon

왜 JavaDocs가 무엇인지 찾는 것으로 시작하지 않으시겠습니까?

http://en.wikipedia.org/wiki/Javadoc

그들이 사용하는 방법의 예는 다음과 같다.

/** 
* Gets the id of the player. 
* 
* @param someParam you'd put a description of the parameter here. 
* @return the id of the object. 
*/ 
public int getId(int someParam) { 
    return this.id; 
}

출처

2014-03-13 06:03:17 Tristan

이것은 당신이 얘기 자바 독입니다 :

/** 
* Subject line 
* 
* <p>Description of the method with optional {@code code} and {@link Object links to Javadoc} 
* </p> 
* 
* <pre> 
* raw input 
* </pre> 
* 
* @param foo first arg 
* @return a bar 
* @throws SomeException if bar goes wrong 
* @see someOtherMethod() 
* @since 2.2.2 
* @author me 
*/ 
int doSomething(final int foo) 
    throws SomeException 
{ 
    // etc 
}

Javadoc 툴 (및 Gradle을하고 받는다는 등 다양한 빌드 시스템에서이 도구를 사용하여 목표)과는 HTML 파일을 생성합니다.

나중에 설명을 추가해야하나요?

실제로 이전에는 협약으로 작성되었습니다. 그리고 필요한 경우에만.

또한 너무 많은 설명서가 있습니까?

예.

출처

2014-03-13 06:03:49 fge

이러한 것들은 javadoc 태그입니다. 과 같이 표시됩니다 위에서 언급 한 두에 대한 http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

그러나 기본 예제 : 당신이 여기에서 찾을 수 있습니다 그들은을 사용하는 방법에 대한 전체 참조

/** 
* Adds two values. 
* 
* @param operand1 - first numeric value for the ADD operation 
* @param operand2 - second numeric value for same purposes 
* @return sum of two operands 
*/ 
public int add(int operand1, int operand2) {...}

Javadoc과 항상 방법이나 변수 또는 클래스 전에 사용 /인터페이스

출처

2014-03-13 06:04:29 Anver

Javadoc style guide은 이러한 태그의 용도를 설명합니다. @param는 파라미터를 기술 해, @return는 반환 값을 기술합니다. (다른 유용한 태그가 몇 가지 있습니다.)

Javadoc은 사용자 의견에서 이 아니라이 아닌 코드에서 설명서를 생성합니다. 메서드의 서명이 출력에 나타납니다. 따라서 은 이미 알고있는 내용을 알려주지 않습니다.. 문서의 목적은 서명에 표현되지 않은 추가 의미를 제공하는 것입니다. 해당 숫자 매개 변수가 특정 범위의 값으로 제한됩니까? 특별한 반환 값이 있습니까 (null과 같은)? 계약서를 문서화하십시오.

너무 많은 문서가 있는지 묻습니다. 예, 있습니다. API 참조 문서는 독자에게 인터페이스를 올바르게 사용하기 위해 알아야하는 정보 만 알려주는 경우에 가장 유용합니다. 따라서 계약을 완전히 문서화하십시오. 그러나 코드가이 인터페이스를 구현하는 방법에 대해 아무런 언급도하지 마십시오. 문서화하고있는 부분에 직접적으로 관련되는 API의 다른 요소 (예 : 다른 클래스 또는 인터페이스)에 링크하십시오 (예 : 누군가 SomeFactory를 사용하여 SomeThing의 인스턴스를 가져와야하는 경우, 문서화중인 클래스).

이것은 몇 문장 이상은 쓰지 말아야한다는 말은 아닙니다. 때로 인터페이스가 복잡하고 더 많은 설명이 필요합니다. 해당 설명이 패키지 개요, 클래스 또는 인터페이스의 최상위 문서 또는 특정 구성원에 속하는지 여부를 고려하십시오. 여러 곳에서 설명을 잘라내어 붙여 넣는다면, 대신 더 높은 수준에서 설명해야한다는 신호 일 수 있습니다.

출처

2014-03-14 02:21:24

Java 문서 - @return 및 @param

답변

관련 문제