Rust: 문서 주석 스타일 가이드 개발

:+1: 이에 대해 논의합니다. 문서를 제공하고 싶지만 완료된 후에는 더 많은 작업을 수행하고 싶지 않습니다. ;)

비교를 위해 표준 Python 스타일은 명령형 "Return ..."을 사용하는 것인데 잘 작동합니다.

http://www.python.org/dev/peps/pep-0257/#one -line-docstrings

Go는 비명령 스타일로 정착했습니다: http://golang.org/pkg/

분류를 위해 방문합니다.

개인적으로 명령형 동사와 마침표를 선호합니다. 문서 주석 스타일에 관해서는, 적어도 언어가 여러 가지 방법을 정의하는 동안은 우리가 다른 방법에 대해 특정 방법을 적용해야 한다고 생각하지 않습니다. 또한 내가 선호하는 방법은

/**
 * doc string
 */

저도 명령형을 선호합니다. Style은 또한 유형과 인수를 참조하기 위한 통합 구문을 포함해야 하므로 rustdoc 적절하게 주석을 달거나 하이퍼링크할 수 있습니다. 그것은 길 아래에 있지만

분류를 위해 방문합니다. 나는 이것에 대해 거의 의견이 없습니다.

설명 스타일:

• C# : Sorts the elements ... http://msdn.microsoft.com/en-gb/library/w56d4y5z%28v=vs.85%29.aspx#United %20Kingdom%20%28영어%29
• C++ : ... sorts the elements ... http://www.sgi.com/tech/stl/sort.html
• 이동 : ... sorts data ... http://golang.org/pkg/sort/#정렬
• 하스켈 : ... takes an element and a list and inserts the element into the list ... http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-List.html
• 자바 : Sorts the specified array ... http://docs.oracle.com/javase/7/docs/api/java/util/Arrays.html
• 루비 : Sorts self in place. http://www.ruby-doc.org/core-2.1.0/Array.html#method -i-sort-21

명령 스타일:

• 오캠 l: ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
• 파이썬 : Sort the items ... http://docs.python.org/2/tutorial/datastructures.html

내가 다음과 같이 말할 때까지 메서드 정의는 아무 것도 하지 않기 때문에 나는 설명적인 버전을 선호합니다.

class Machine
{
    // Self-destructs the machine, if necessary.
    void self_destruct();
};

// Self-destruct!
if ( emergency )
  machine.self_destruct();

나는 kud1ing의 주장에 합리적입니다. 또한 문서에 나와 있는 방식으로 한 줄을 소리 내어 읽는 경우:

0 더하기 ID 0을 반환합니다.

그런 다음 선언적 형식은 실제 문장 "zero" returns the additive identity, 0. 만듭니다.

@Armavica : 실제로 The method "zero" returns the additive identity, 0 의 축약형입니다.

문서화 및 인터페이스는 청중에게 무언가를 제시하고 있습니다. 구현에서 무슨 일이/어떻게/왜 일어나는지 설명할 때 명령형이 더 합리적이라고 생각합니다.

문서의 예제 스타일에 대한 https://github.com/mozilla/rust/issues/9403 도 있습니다.

쟁기.

참조 https://github.com/mozilla/rust/issues/12928

여기 주석에서 설명하는 스타일(예: "바이트를 문자열로 변환합니다.")이 명령형 스타일("바이트를 문자열로 변환합니다.")보다 더 많이 사용되는 것 같습니다. 우리가 어떤 길을 가는지는 크게 신경쓰지 않지만, 이에 대해 공식적인 결정을 내리는 것이 좋을 것입니다.

이것을 명령형이라고 부르는 것은 잘못된 것이라고 생각합니다. 아무에게도 지시하지 않기 때문에 반드시 필요한 것은 아닙니다. 나는 그것이 1인칭 현재 암시라고 생각한다. 글을 쓰고 싶은 충동이

/// Frob the twaddle.
fn frob() {}

"나는 기능이다. 나는 무엇을 할까?"라는 마음가짐에서 비롯된 것이므로 1인칭 현재 직설법입니다.

그러나 문서를 읽을 때 대부분의 독자는 자연스럽게 함수를 1인칭 주제가 아닌 3인칭 단수 주제로 취급합니다. 이를 위해 문서는 1인칭이 아닌 3인칭 단수로 작성되어야 합니다.

이것을 1인칭 현재 표시가 아닌 명령형으로 간주하기 위해 내가 볼 수 있는 유일한 합리적인 주장은 독스트링이 사용자가 구현해야 하는 함수 선언을 설명할 때입니다. 이것은 객체지향 언어에서 매우 일반적이지만, 러스트에서는 특성 메소드에만 적용됩니다. 이 경우는 메서드를 올바르게 구현하기 위해 수행해야 하는 작업을 알려 주기 때문에 명령형 사용을 제안합니다.

그러나 나는 이 주장이 설득력이 있다고 생각하지 않는다. 문서화의 주요 사용 사례는 독자에게 API를 구현하는 방법이 아니라 API를 _사용_하는 방법을 알려주는 것입니다. API의 사용 횟수는 구현 횟수를 훨씬 능가합니다(가장 난해한 경우를 제외하고는 모두). 따라서 나는 특성 방법에 대해서도 명령형을 사용하는 것보다 3인칭 단수의 현재 직설법을 사용하는 것이 더 합리적이라고 생각합니다.

처리해야 할 또 다른 사항: 하이픈 또는 엔 대시:

https://en.wikipedia.org/wiki/Dash#Relationships_and_connections

이러한 좌표/관계/연결 유형의 용어에서 하이픈 대신 엔 대시를 선호하는 것은 고유한 철자법 "정확성"이 아니라 스타일 선호도의 문제입니다. 둘 다 똑같이 "올바른" 것이고, 각각은 일부 스타일 가이드에서 선호되는 스타일입니다.

RFC를 제출했습니다: https://github.com/rust-lang/rfcs/pull/505