LINUX.ORG.RU

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

 ,


0

1

Библиотека, чистый си.

Имеет ли смысл использовать doxygen? Он же, ЕМНИП, ориентирован на ООП код.

Если имеет, то в каком виде? В хидере перед сигнатурой функции, в сорце перед сигнатурой функции? В отдельном файле?

Если не имеет, то чем подобным заменить? Стоит ли писать свой велосипед, заточенный конкретно под си-код? Больше велосипедов, хороших и разных, или нахрен велосипеды?

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

anonymous ()

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

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

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

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

MKuznetsov ★★★★★ ()
Ответ на: комментарий от MKuznetsov

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

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

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

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

sambist ★★ ()
Ответ на: комментарий от sambist

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

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

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

MKuznetsov ★★★★★ ()
Ответ на: комментарий от sambist

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

beastie ★★★★★ ()
Последнее исправление: beastie (всего исправлений: 1)
Ответ на: комментарий от MKuznetsov

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

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

SmlRasterDrawTetragonGradientRounded
.

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

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

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

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

sambist ★★ ()
Ответ на: комментарий от beastie

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

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

sambist ★★ ()
Ответ на: комментарий от MKuznetsov

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

nanoolinux ★★★★ ()
Последнее исправление: nanoolinux (всего исправлений: 1)

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

nanoolinux ★★★★ ()
Ответ на: комментарий от sambist

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

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

beastie ★★★★★ ()
Ответ на: комментарий от anonymous

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

sambist ★★ ()
Ответ на: комментарий от beastie

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

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

sambist ★★ ()
Ответ на: комментарий от beastie

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

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

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

sambist ★★ ()
Последнее исправление: sambist (всего исправлений: 1)
Ответ на: комментарий от sambist

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

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

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

beastie ★★★★★ ()
Последнее исправление: beastie (всего исправлений: 1)
Ответ на: комментарий от beastie

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

anonymous ()
Ответ на: комментарий от beastie

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

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

sambist ★★ ()
Ответ на: комментарий от sambist

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

nanoolinux ★★★★ ()
Ответ на: комментарий от sambist

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

nanoolinux ★★★★ ()
Ответ на: комментарий от beastie

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

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)));

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

и/или мане.

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

sambist ★★ ()
Ответ на: комментарий от nanoolinux

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

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

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

sambist ★★ ()
Ответ на: комментарий от sambist

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

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

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

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

beastie ★★★★★ ()
Ответ на: комментарий от beastie

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

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

sambist ★★ ()
Ответ на: комментарий от sambist

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

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

mashina ★★★★★ ()
Ответ на: комментарий от sambist

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

nanoolinux ★★★★ ()
Ответ на: комментарий от nanoolinux

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

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

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

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

MKuznetsov ★★★★★ ()

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

peregrine ★★★★★ ()
Ответ на: комментарий от MKuznetsov

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

nanoolinux ★★★★ ()
Ответ на: комментарий от sambist

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

typedef void (*SmlEventCallback)(int window, int event, int info, int idx);
i-rinat ★★★★★ ()
Ответ на: комментарий от sambist

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

false ★★★★★ ()
Ответ на: комментарий от buddhist

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

anonymous ()
Ответ на: комментарий от sambist

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

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

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

i-rinat ★★★★★ ()
Последнее исправление: i-rinat (всего исправлений: 2)

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

anonymous ()
Ответ на: комментарий от buddhist

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

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

cord ()
Ответ на: комментарий от i-rinat

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

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

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

SmlErrors SmlRasterDrawTetrR (SmlIndex index, SmlTetragon tetragon, SmlTetragon corners, SmlColour colour, SmlFillStyle fstyle, SmlLineStyle lstyle);
sambist ★★ ()
Ответ на: комментарий от sambist

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

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

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

i-rinat ★★★★★ ()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.