Очень может быть. Но, вы не задумывались, что существуют и другие парадигмы (вот это поворот 😂) и это надо учитывать когда в общий чат!?!

Ничего себе, вы за весь коллектив чата в 1100 человек говорите? Не пренебрежительно ли?

По поводу первого пункта не понял

это же двухсторонняя дорога, не правда ли? 😉

Если апеллировать в "высоким тех. стандартам" (ваши слова), то логично предположить, что и подобного стоит ожидать и в остальном (или я напрасно надеюсь)... Но, исходя из сказанного многим ранее (хант на вакансию, ответы и т.д.) - мне, например, не показалось. что они, эти стандарты, имеют место быть.

Ребят, давайте заканчивать.
Все уперлись в своё мировозрение.

Если подбить:
- Евгений хотел зашарить вакансию, не оформил как хотелось бы и поэтому возникли вопросы плюс пара неоднозначных шуток
- Ребята хотели большей прозрачности от Евгения и вакансии

Давайте быть конструктивными

Давай так. Шутка (как выясняется, это была шутка) неудачная. И вместо того, чтобы сказать, что хрень, а проект ОК и сейчас переформулирую- началась словесная тягомотина .

Кто может помочь советами по "теория написании документации в Elixir"? Тут вообщем очень простая ситуация:
Есть функция в модуле. Эта функция получает получает параметры и возвращает значение. Если параметров много или мало, то возвращается :error, иначе функция выполнятся. Во время выполнение получение параметры могут не соответствовать условию, в этом случаи так же возвращается :error. Если всё правильно, то возвращается тупл с атомом и мапом. Я посмотрел в нескольких исходниках, в каких-то статьях, но так и до конца не понял: мне стоит описывать каждый случай вызома, скажем с правильным количество параметров и неправильным, с правильными входящими данными и с неправильными, или хватит всего один пример?

Как вы это обычно делаете?

давай по пунктам:
1. Если передаваемые параметры не соответствуют арности вызываемой ф-ции, то выбросится соответствующее исключение.
2. "не соответствует условию" - речь о guards?

1. Исключение выбрасывается(в виде атома error), но стоит ли эту часть тоже включать в докементацию?
2. Нет, просто bad requst/invalid inputs, что-то такое.

док-ция описывает валидные параметры на вход и их пример + выхлоп ф-ции... (остальное, ложится на код)...

мне обычно хватает spec с перечислением всех возможных результатов, но это подразумевает что ошибки говорят сами за себя, например user_not_found, invalid_id. Если ошибки неоднозначные, то можно в комментарии перечислить все возможные ошибки списком и кратко описать что они значат.

В смысле "выхлоп"?

субъективно, мне нравится оформление оф. док-ции эрланг, вот пример:

compile(Regexp, Options) -> {ok, MP} | {error, ErrSpec}
 
Types
Regexp = iodata() | unicode:charlist()
Options = [Option]
Option = compile_option()
MP = mp()
ErrSpec =
   {ErrString :: string(), Position :: integer() >= 0}

Все четко и понятно.

Ясно, значит увлекаться с написанием документации не стоит.

И да, spec  - писать хороший тон. (хотя. часто встречаю ее отсутствие)

👌 очень полезное увлечение.

не ну если пишешь опен сорс либу то лучше более подробно писать документацию, если для себя и команды - то нет необходимости

А это джуну не покажешь. Написание докементации для языка и для магазина совсем другие, то что сеньёру сразу зашло джун с трудом поймёт.