Сообщение Re[5]: Инструмент для документирования C/C++ от 29.12.2016 19:52
Изменено 29.12.2016 19:53 bnk
Здравствуйте, vovkos, Вы писали:
bnk>>Наибольшую ценность имеют именно написанные вручную тексты (getting started, tutorial, samples, etc), а не гроссбухи из функций и неймспейсов.
V>А разве не хочется, чтобы из этих самых Getting Started и Tutorial (которые, безусловно, можно писать только руками), были ссылки на описания функций в гроссбухе? Чтобы хотя бы можно было посмотреть, что за аргументы принимает функция, которую вы демонстрируете в сниппете -- тут ведь IDE-шные Ctrl+Click и mouse-hover не сработают!
Не, ссылки на сигнатуры не нужны. Все равно же печатать будешь в ide, раньше тебе это просто не нужно знать, int там или long. Достаточно понять общую картину, детали на этапе чтения документации бесполезны.
А вот уже для корпоративных (не публичных!) фреймворков ценность доков далеко не ноль. Да на самом деле и для личных тоже -- процесс документирования помогает разложить всё по полочкам и выявить несуразности в API, которые могут и не замечаться при использовании.
Агащас. Ни разу не видел пользы в корпоративных проектах от автогенернной документации. Согласно моему опыту, обычно это делается ради галочки, на самом деле никто это не читает.
bnk>>Наибольшую ценность имеют именно написанные вручную тексты (getting started, tutorial, samples, etc), а не гроссбухи из функций и неймспейсов.
V>А разве не хочется, чтобы из этих самых Getting Started и Tutorial (которые, безусловно, можно писать только руками), были ссылки на описания функций в гроссбухе? Чтобы хотя бы можно было посмотреть, что за аргументы принимает функция, которую вы демонстрируете в сниппете -- тут ведь IDE-шные Ctrl+Click и mouse-hover не сработают!
Не, ссылки на сигнатуры не нужны. Все равно же печатать будешь в ide, раньше тебе это просто не нужно знать, int там или long. Достаточно понять общую картину, детали на этапе чтения документации бесполезны.
А вот уже для корпоративных (не публичных!) фреймворков ценность доков далеко не ноль. Да на самом деле и для личных тоже -- процесс документирования помогает разложить всё по полочкам и выявить несуразности в API, которые могут и не замечаться при использовании.
Агащас. Ни разу не видел пользы в корпоративных проектах от автогенернной документации. Согласно моему опыту, обычно это делается ради галочки, на самом деле никто это не читает.
Re[5]: Инструмент для документирования C/C++
Здравствуйте, vovkos, Вы писали:
bnk>>Наибольшую ценность имеют именно написанные вручную тексты (getting started, tutorial, samples, etc), а не гроссбухи из функций и неймспейсов.
V>А разве не хочется, чтобы из этих самых Getting Started и Tutorial (которые, безусловно, можно писать только руками), были ссылки на описания функций в гроссбухе? Чтобы хотя бы можно было посмотреть, что за аргументы принимает функция, которую вы демонстрируете в сниппете -- тут ведь IDE-шные Ctrl+Click и mouse-hover не сработают!
Не, ссылки на сигнатуры не нужны. Все равно же печатать будешь в ide, раньше тебе это просто не нужно знать, int там или long. Достаточно понять общую картину, детали на этапе чтения документации бесполезны.
V>А вот уже для корпоративных (не публичных!) фреймворков ценность доков далеко не ноль. Да на самом деле и для личных тоже -- процесс документирования помогает разложить всё по полочкам и выявить несуразности в API, которые могут и не замечаться при использовании.
Агащас. Ни разу не видел пользы в корпоративных проектах от автогенернной документации. Согласно моему опыту, обычно это делается ради галочки, на самом деле никто это не читает.
bnk>>Наибольшую ценность имеют именно написанные вручную тексты (getting started, tutorial, samples, etc), а не гроссбухи из функций и неймспейсов.
V>А разве не хочется, чтобы из этих самых Getting Started и Tutorial (которые, безусловно, можно писать только руками), были ссылки на описания функций в гроссбухе? Чтобы хотя бы можно было посмотреть, что за аргументы принимает функция, которую вы демонстрируете в сниппете -- тут ведь IDE-шные Ctrl+Click и mouse-hover не сработают!
Не, ссылки на сигнатуры не нужны. Все равно же печатать будешь в ide, раньше тебе это просто не нужно знать, int там или long. Достаточно понять общую картину, детали на этапе чтения документации бесполезны.
V>А вот уже для корпоративных (не публичных!) фреймворков ценность доков далеко не ноль. Да на самом деле и для личных тоже -- процесс документирования помогает разложить всё по полочкам и выявить несуразности в API, которые могут и не замечаться при использовании.
Агащас. Ни разу не видел пользы в корпоративных проектах от автогенернной документации. Согласно моему опыту, обычно это делается ради галочки, на самом деле никто это не читает.