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 ★★ ()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

beastie ★★★★★ ()
Ответ на: комментарий от 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

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

beastie ★★★★★ ()
Ответ на: комментарий от 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 ★★★★★ ()
Ответ на: комментарий от sambist

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

buddhist ★★★★★ ()
Ответ на: комментарий от 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 ()

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

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

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

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

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

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

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

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

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

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