Rust: Разработайте руководство по стилю документов и комментариев

: +1: за обсуждение этого. Я хочу добавить документы, но не хочу больше работать за вас после того, как это будет сделано. ;)

Для сравнения, стандартный стиль Python заключается в использовании повелительного слова «Вернуть…», которое, как мне кажется, работает хорошо:

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

Go остановился на не императивном стиле: http://golang.org/pkg/

Посещение для сортировки.

Лично я предпочитаю повелительные глаголы и точку в конце. Что касается стиля комментариев документа, я не думаю, что мы должны применять какой-то конкретный способ к другому, по крайней мере, пока язык определяет несколько способов сделать это. Кроме того, я предпочитаю

/**
 * doc string
 */

Я также предпочитаю императив. Стиль также должен включать унифицированный синтаксис для обращения к типам и аргументам, поэтому rustdoc может правильно аннотировать их / делать гиперссылки. Это в будущем

Посещение для сортировки. У меня очень мало мнения по этому поводу.

Описательный стиль:

• C # : Sorts the elements ... http://msdn.microsoft.com/en-gb/library/w56d4y5z%28v=vs.85%29.aspx#United% 20Kingdom% 20% 28English% 29
• C ++ : ... sorts the elements ... http://www.sgi.com/tech/stl/sort.html
• Перейти : ... sorts data ... http://golang.org/pkg/sort/#Sort
• Хаскель l: ... 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
• Java : 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

Императивный стиль:

• Ocam l: ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
• Python : 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();

Я разумно согласен с аргументами Кудиинга. Кроме того, если вы прочитаете строку так, как она представлена ​​в документе:

ноль Возвращает аддитивную идентичность, 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

Из комментариев здесь описательный стиль (например, «Преобразует байт в строку») кажется более популярным, чем императивный стиль («Преобразование байта в строку»). Меня не очень волнует, каким путем мы пойдем, но было бы неплохо получить официальное решение по этому поводу.

Я считаю, что называть это императивным стилем неправильно. Это не обязательно, потому что это никому не приказывает что-либо делать. Я думаю, это показательно от первого лица. Я подозреваю, что желание написать

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

проистекает из образа мышления «Я - функция. Что мне делать?», так что это указание от первого лица.

Однако при чтении документации большинство читателей, естественно, будут рассматривать функцию как единичный субъект от третьего лица, а не как субъект от первого лица. С этой целью документация должна быть написана от третьего лица единственного числа, а не от первого лица.

Единственный разумный аргумент, который я могу видеть в пользу того, чтобы считать это императивом, а не показательным от первого лица, - это когда строка документации описывает объявление функции, которую, как ожидается, будет реализовывать пользователь. Это очень распространено в объектно-ориентированных языках, но в Rust это применимо только к методам трейтов. В этом случае предлагается использовать императив, потому что он говорит вам, что вы должны сделать, чтобы правильно реализовать метод.

Но я не считаю этот аргумент убедительным. Основной вариант использования документации - рассказать читателю, как _использовать_ API, а не как его реализовать. Количество использований API значительно превышает количество реализаций (во всех случаях, кроме самых эзотерических). Поэтому я считаю, что имеет больше смысла использовать настоящее изъявительное слово в единственном числе от третьего лица, чем повелительное наклонение, даже для методов определения черт.

Еще одна вещь, с которой нужно иметь дело: hypens или en dashes:

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

Предпочтение короткого тире вместо дефиса в этих типах терминов «координаты / отношения / соединения» является вопросом предпочтения стиля, а не присущей орфографической «правильности»; оба одинаково «правильны», и каждый из них является предпочтительным в некоторых руководствах по стилю.

Я отправил RFC: https://github.com/rust-lang/rfcs/pull/505