Имеет ли смысл использовать doxygen?

да; в достаточном; хидере описание, сорце комментарии и внутренняя реализация; нет; -; конечно; больше хороших.

Больше велосипедов, хороших и разных

это правильно.

хотя считаю хорошей документацией - документацию не совмещённую с кодом в одном флаконе. В коде должно быть минимум действительно важных и актуальных коментов, сам по себе код должен легко читаться.

когда вижу что-то типа /** @class theDog - класс «собака» */ хочется поубивать сразу того кто это написал, того кому без «этого» непонятно и манагера который это потребовал

В коде должно быть минимум действительно важных и актуальных коментов, сам по себе код должен легко читаться.

Ок, пример из жизни (конкретно текущего проекта). Модуль растровой графики, сигнатура функции:

SmlErrors SmlRasterDrawTetrGR(SmlIndex index, SmlTetragon tetragon, SmlTetragon corners, SmlGradient grad, SmlFStyle fstyle, SmlLStyle lstyle);

Без поясняющих параметры комментариев вам понятны они все?

FreeRTOS: task.h, tasks.c

Без поясняющих параметры комментариев вам понятны они все?

мне непонятны параметры без пояснения что делает функция. Коментария навроде «четырёхугольник с градиентной заливкой» наверное достаточно, если есть описания назначения типов SmlTetragon, SmlFStyle и так далее. Причём такой комент нужен только если есть(предвидятся) SmlDrawTriangleRF. И я бы предпочёл чтоб функция звалась TriangleRadialFill (без лишних префиксов, очевидных слов и странных абревиатур)

SmlFStyle кстати не самое удачное название. На префикс юзеру наплевать, у вас всё SmlXXX, а вот что такое F приходится задумываться

Для С имхо лучше всего self-docementing, всякие doxygen и другие noweb не особенно прижились.

А теперь убери никому ненужный Sml префикс и всё становится более-менее читабельно. (Не, иногда префикс всё же нужен, но если его мысленно вычеркнуть, то более-менее всё ясно.)

И я бы предпочёл чтоб функция звалась TriangleRadialFill (без лишних префиксов, очевидных слов и странных абревиатур)

Тут проблема в том, что я в планах имею добавить векторную графику, а первое слово после префикса мне заменяет имя класса. По поводу аббревиатур: G - Gradient, R - Rounded. Если писать целиком, то тут получается имя функции почти на весь экран (мы ж не в жабе):

SmlRasterDrawTetragonGradientRounded

очевидных слов

Предлагаете вычеркнуть Draw?

SmlFStyle кстати не самое удачное название. На префикс юзеру наплевать, у вас всё SmlXXX, а вот что такое F приходится задумываться

Принято, поменяю на SmlFillStyle & SmlLineStyle, спасибо.

А теперь убери никому ненужный Sml префикс и всё становится более-менее читабельно.

У Qt это Q, У Gtk Gtk, и т.д. Каждая либа тянет свой префикс чтобы можно было отличить имена библиотечных функций\типов\констант от пользовательских.

Конечно. У него даже опция есть, оптимизировать для с, неаомню как называется.

OPTIMIZE_OUTPUT_FOR_C

В дохигене обычно на странице есть ссылка на файл без разметки.

Короче, пацаны не шарят. У меня под это дело настроен специальный апачи для интранета компании. Когда собираеться релиз туда автоматом всё аплоадиться. Причём сразу две версии - для разработчика и для юзера. Очень удобно.

Да знаю я, только часто это абсолютно не нужно. Но все, как мартышки повторяют.

В частности очень маловероятно, что с названием функции вроде RasterDrawTetrGR ты даже гипотетически рискуешь нарваться на коллизии. (Тоже касается и типов.)

а типа Index (SmlIndex) это тоже касается?

А почему бы не использовать просто int? От куда эта тяга всё переименовывать?

правильно, почему любимую обязательно звать Маша, зачем эти зайка, котик.

Point, Rect, Circle, Line, Curve, Colour, Errors, Gradient, ну и далее по списку

От куда эта тяга всё переименовывать?

Это называется повышение читабельности и информативности. Вот когда поймете, почему в винде в WinAPI вместо int два десятка типов типа *Handle, тогда поймете, почему это важно.

Тут скорее generic имя «девушка».

Ты это сейчас серьёзно?

Скорее наоборот. int — сразу ясно, о чём речь, а что скрывается за *Handle — одному Биллу известно.

int — сразу ясно, о чём речь, а что скрывается за *Handle — одному Биллу известно.

А плевать, что скрывается под Handle. Для вас это должно быть черным ящиком. Если вам в сигнатуре написано func(int, int, int, int, int, int) - куда положите результат функции CreateFont, куда CreateWindow, куда CreatePainter, куда CreateSurface, а что - координаты?

Вариант номер два:
func(WindowHandle, FontHandle, PainterHandle, SurfaceHandle, int, int)

Имеет ли смысл использовать doxygen? (комментарий)

Вариант номер три (и имхо самый верный):

func(int WindowHandle, int FontHandle, int PainterHandle, int SurfaceHandle, int x, int y)

Одним словом, не плоди сущности без надобности.

не, это не правильно, если предполагается указатель, то он должен быть указателем, никак не int.

Вариант номер три (и имхо самый верный):

Трижды «ха». Вам перечислить случаи, когда от функции доступно только имя и сигнатура без имен? Начиная от Qt-шных сигнал-слотов и заканчивая истинно сишными колбэками и указателями на функцию.

Интересная тз, но я думаю это как коммунизм - идея вроде ничего но на практике какое-то говно.

Ну, перечисли. Из того, с чем мне приходилось встречаться, всё это обычно указано в шапке и/или мане.

Сигнатурам без имён твои тайпдефы не помогут. А назначение сигнала valueChanged у спинбокса или disconnected у сокета понять проще чем ldhdjfbdhshdjfHandle например.

В С++ в хидере сигнатура метода класса может не включать имена параметров. Т.е. то, когда их пишут - это только добрая воля разработчика. Вполне легально такое:

class aaa
{
   int p(int, int);
}

aaa::p(int x, int y)
{
 ...
}

Встречал такое и не раз, в основном в софте, который отдавался на аутсорс.

Вариант с сигнал\слотами уже сказал - к слову такая система есть не только в Qt, GTK тоже использует нечто подобное, в Wx не помню.

connect(this, SIGNAL(textchange(QString, int, int, int, int, int)), gui, SLOT(gollier(QString, int, int, int, int, int)));

Коллбеки тоже уже назвал. Пример выдирать из проекта не буду, но, ЕМНИП, в типа «указатель на функцию», имена параметров вообще не указывают (не помню, скомпилится с именами или нет).

и/или мане.

Вот. ВОООООТ! В мане. Т.е. вместо того, чтобы инстинктивно понять, что круглая фигурка идет в круглое отверстие, а квадратная в квадратная мне надо искать по какому-то идиотскому сайту расшифровку параметров функции. Набуя?

Сигнатурам без имён твои тайпдефы не помогут

typedef void (* SmlEventCallback)(SmlWindow, SmlEvent, SmlInfo, int);
typedef void (* SmlEventCallback)(int, int, int, int);

Сразу стало так офигенно понятно и чисто! Пойду удалю все тайпдефы, спасибо.

Вполне легально такое

Легально, но bad habits. (Говорит, впрочем, только о низком качестве библиотеки.)

искать по какому-то идиотскому сайту

У тебя какая-то неправильная документация. ;)

У тебя какая-то неправильная документация. ;)

Само то, что для того чтобы писать код мне нужен интернет - уже, как вы назвали, bad habits.

Это называется повышение читабельности и информативности. Вот когда поймете, почему в винде в WinAPI вместо int два десятка типов типа *Handle, тогда поймете, почему это важно.

С читабельностью это не связано, хэндлы просто «указатели» на разные типы объектов. Если в WinAPI что-то оказалось удобным, то это чисто случайно.

Думаю, что это дело личных предпочтений. Мне удобнее в доки глянуть, чем догадываться по сигнатуре чего она там принимает, что делает и что возвращает.

В дохигене обычно на странице есть ссылка на файл без разметки

Когда собираеться релиз туда автоматом всё аплоадиться. Причём сразу две версии - для разработчика и для юзера. Очень удобно.

две версии чего? исходника?? с коментами и без них что-ли...если так, то вы укурились

а вы заодно ещё версия для заказчиков так не делаете - с разными копирайтными шапками? :)

Если ты пишешь код, который планируется поддерживать только своими силами (а как надоест - проект загнётся), то нет. Если что-то более грандиозное с надеждой, что кто-то ещё будет разрабатывать твой код, то стоит.

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

Нет. Дохи удаляет только разметку для себя, а всё остальное оставляет. Короче, чувак, не тупи, это отличный инструмент для документации.

Сразу стало так офигенно понятно и чисто!

typedef void (*SmlEventCallback)(int window, int event, int info, int idx);

Тут недавно пришлось выколупывать кусок функционала из glib2, так вот - иди ты со своими тайпдефами по делу и без в лес.

Поддерживаю.

В чём проблема? Я не писал биндингов, мне интересно.

Модуль растровой графики, сигнатура функции

Интерфейс у функции страшненький, он перегружен, в нём слишком много параметров. Почему бы не ввести внутреннее состояние, как в Cairo или OpenGL? Если я не хочу градиент, что мне передать как параметр? Почему пользователю должно быть это очевидно?

И имя Sml очень неудачное, в поисковиках оно тонет под упоминаниями SML/NJ. Даже по запросу SmlErrors видны только исходники libsyncml.

Зависит от задач, у меня asciidoc + noweb.

А потом люди, пишущие биндинги к твоей говнолибе должны будут страдать, перелопачивая тонный тайпдефов

Таких людей мало, зато остальным будет проще соблюдать типы.

Да, но скорее как справочник по API. Нормальную документацию это не заменит.

Почему бы не ввести внутреннее состояние, как в Cairo или OpenGL?

Потокобезопасней делать это одной функцией. Плюс избавляет от необходимости заводить внутренний массив для сохранения параметров для тех текстур, которые вы сейчас в разеных потоках обрабатываете.

Если я не хочу градиент, что мне передать как параметр?

SmlErrors SmlRasterDrawTetrR (SmlIndex index, SmlTetragon tetragon, SmlTetragon corners, SmlColour colour, SmlFillStyle fstyle, SmlLineStyle lstyle);

Потокобезопасней делать это одной функцией

Пока в разных потоках происходит работа с разными контекстами, cairo вполне потокобезопасен. Это надо специально напортачить, завязать работу на глобальные переменные, чтобы сделать такой интерфейс не потокобезопасным. Если в разных потоках рисовать в одном контексте, с пересекающимися объектами всё равно выйдут косяки, какой интерфейс не используй. И всё равно сериализацию придётся делать в клиентском коде.

Ты сам-то хоть используешь эту библиотеку, которую пишешь?