Как процедирате когато искате в проекта на даден софтуерен продукт да добавите разни странични данни - документация например?
Едното масово срещано явление е анотиране на кода с разни таг-ове, най-често в коментарите (доксиген-а).
Контекстът на питането ми е че искам да мога да закача към определени точки в кода "хиперлинк-ове"/URL-и (примерно) с разгърната информация.
Конкретните ми търсения имат лека връзка с предишната тема "нещо като syslog?" - имаме точка в кода, в която софтуера прави някаква проверка (условие) и реагира - например вдига "аларма". Тази аларма (грешка) трябва да се разпише детайлно и това описание да се "движи" в синхрон с кода - т.е. съзаването на нова ревизия на сорса да може да добави/промени/махне някаква такава грешка. Или с други думи, от кода трябва да може да се "извлече" тази инфомация, и то точно от определен версия на сорса, и определена билд конфифурация "#define EXTENDED_FUNC_ENABLE 1" например.
При доксигена идеята е всичката тази мета-информация да се закачи към сорса директно - в самия хедър или C файл примерно. Това подпомага някой аспекти, но води до други проблеми - не може да се слага UNICODE, кода става нечетим (понякога описанията са в пъти повече от редовете реален код).
Та моето питане е как правим "референция" от ред в кода към външен ресурс (файл, URL, идентификатор, ...)?
Пак покрай лог/трейс темата видях една екстра на gnu инструментите (gcc/gdb) която не познавах досега - и това е "#line" директивата. Даже си мисля че не е gcc специфична понеже е спомената в MISRA правилата... Но идеята на тази директива е че написвайки:

ще укажем по стандартен начин на инструментариума (гцц/гдб) че в някакъв файл /doc/errors.txt, на ред 7-ми има нещо което е асоциирано с точката в C кода ни тук. Това го ползват когато C кода "if a>b" е генериран от някакво по-високо ниво - т.е. имало е сорс на друг език и някакъв инструмент (код генератор) го е транслирал на C, добавяйки "връзка" откъде е това. Това го пробвах и даже работи - кара еклипса да отвори другия файл и да се мъкне по линиите му докато дебъгвам

Обратно по темата, търся идеи как да "маркирам" определени точки в кода (предполагам че там ще имам макроси) и те да могат да сочат навън. Конкретно това с "#line" не ми е нужно понеже нямам нужда от gdb поддръжка, така че си мисля за нещо custom. Дали специфичен таг от сорта на "\brief" на доксиген-а, или нещо такова.

Малко е неясно защо го правя, но да кажем че в процеса на разработката на кода е имало едно ниво на дизайн преди "кодирането" което е създало някаква информация - модел (UML, математически, ...) или пък документ-спецификация. И целта ми е без да копирам информацията от тези XML/matlab/docx файлове (в доксиген коментари) да мога да покажа причинно-следствената връзка.

Виждането ми е че на местата в кода, където искам да направя тези връзки, трябва да сложа някакъв маркер - идентификатор например, който да е ключа за извличане на информацията от външен ресурс (както е 7-цата в примера за #line).
Мислех доколко __FILE__, __LINE__, __COUNTER__ могат да се ползват, но клоня към идеята че няма да стане - в смисъл редактиране на код някъде из сорса, било то коментар или празен ред, ще смени __LINE__ и ще счупи връзката към връзката... Counter е по-добре, но пак ще е странно когато се редактира и се добави нова грешка в същия файл. Евентуално __FUNCTION__ май е най-малкото като единица, и брояч локален за функцията (__COUNTER__ който се рестартира във всяка функция) може да е най-лекото, но и това някак си не ме грабва като решение.
Друга посока беше да ползвам обратното - т.е. във файла "/doc/errors.txt" да имам парчета код около линията в сорса за която важи дадената грешка - по подобие на patch файловете които чрез един-два реда преди и след мястото описват точката във файла, която ще променят - е, аз не искам да променям а само да намеря линията. Така дори кода да се премести в друга функция има шанс да бъде намерен... може би?

Всичките тия условности май са решени (заобиколени?) с подхода на доксигена - за да не се разместят нещата ще ги сложим заедно и ако някой премести реда с условието и грешката трябва да премести и "мета" данните.

Една от целите на цялото упражнение, макар и не единствена, е да се построи система (инструментариум) който да може да извлече (автоматично) списък и детайлно описание на всички генерирани грешки в определен сорс (версия, проектни настройки - билд конфигурация). Това е ценно понеже от една и съща сорс база може да се правят няколко "артефакта" - elf/hex-ове за различни продукти например. Ако някаква функционалност е изключена в единия билд е полезно да имаме актуална информация - т.е. редуциран списък на грешките.

Пак с препратка към другата тема, lttng имат идея и за това - при тях местата на рапортуване на грешки (трейсове всъщност, викат им tracepoints) се описват декларативно в кода - хедърче със структурата на данните и информация (метаданни) за дадената грешка. Ако това се приложи може да значи че оня идентификатор, за който се чудя, може да е отделен макрос от типа на LOG_ERR_MyError3Crc - та този макрос или частта "MyError3Crc" е ключа/идентификатора и той ще присъства в сорса където е условието за вдигане на грешка, и във текстовия (условно - xml, db, ...) файл или като URL/URI в някаква информационна система.
Имам нужда от отделен макрос за всяка грешка за да мога да променям параметрите. Типичното при логване са variadic макросите с променлив брой аргументи - това е за улеснение, но страда откъм детайлност на информацията и консумация на ресурс. Подходът (пак от lttng...) е дадената "трейс точка" да обявява че и трябва да изплюе един аргумент тип int16_t примерно. Следващата трейс точка може да иска два int16_t, или 5 uint32_t, поради контекста на проверките които прави и данните с които работи.
Та ако макросите са отделни (а не един "централен" LOG_ERR(...) ) имам шанса да постигна красотата на lttng решението (или, с други думи, да се възползвам безцеремонно от техните идеи и реализацията им ... )

Същият подход мисля че е подходящ за всякакви "експортирани" неща от софтуерен продукт - тук загатвам за подточката "грешки" или генерирани събития, но логиката трябва да може да се приложи и за входни такива - данни, настройки, конфигурации, методи, входни събития. Т.е. и там бих искал да мога да направя референция към заданието за да се знае защо съм написал "if (a>b) ...".

Edit: Мислейки още малко по темата си правя извода че ако "връзката" която е C сорса е достатъчно ясна (т.е. не е ред във файл а примерно абсолютна локация е някаква йерархия) няма да имам проблемите с разсинхронизирането - тях бих ги имал ако сложа още едно ниво на прехвърляне, т.е. ако има онова "#line 7 "file.txt", което би работило ако на line 7 там има абсолютен линк.

Както обикновено ми е трудно да ти проследя мисълта...

При doxygen ако искаш нещо по-красиво е най-добре да си организираш в отделни doxygen (обикновено *.md) файлове. Там си оформяш структурата, пишеш си излияния, чератеш блок схеми, картинки и т.н. Структурата я задаваш с различни тагове (page, subpage и т.н.). Отделно в сорсовете като документираш нещо може да му кажеш къде да отиде във въпросната структура.
С две думи доксигена позволява да сглобяваш сорсове, текстове и тем подобни в каквато организация искаш и какъвто изходен формат искаш.
Няма нужда да си мешаш файловете. Важното е да си направиш добро етикиране по което можеш да търсиш. Хващаш даден етикет и еклипса веднага ще ти покаже в кои сорсове, в кои доксиген файлове го има... А пък и ти като описваш дадена функция, да кажем за нивото на сондажа и знаеш че имаш някъде друга информация винаги може да сложиш @see еди какво си. Линкът е достатъчен, не е нужно да вмъкваш самата информация в сорса.

За другото - съобщения, грешки и т.н. в сорсовете по принцип се убеждавам че е най-добре да се изнесени. В сорса примерно ползваш ERROR_MESSAGE_BLA_BLA... В отделен файл са всички такива и си ги дефинираш както искаш. Отделен е, защото ако се наложи да си преведеш продукта от български на албански примерно няма как да дадеш сорсовете на преводача. Даваш му един файл с много просто форматиране тъй че да не трябва да разбира от програмиране за да ти го преведе.

Да, точно това търся - като гледах доксигена не съм забелязал това "@see", може би е напълно достатъчно за моите цели - единствената екстра която мога да искам е да има програмен начин да поискам от доксигена да ми изкара репорт на ползванията на @see примерно в даден код.
А това за външната документация и аз го споделям и затова пуснах темата - кой как го прави за да го постигне.
Ако пък имаш подръка конкретни примери (линкове) на разписани всички тия неща ще съм благодарен - не че не мога да преровя за "@see", но може би някъде има развити по-дълбоко нещата, или има и други алтернатива на доксигена - видях че apple има някакво тяхно, но не виждам предимства. Особено предвид на хубавия плъгин за еклипс за доксиген - eclox: https://anb0s.github.io/eclox/
Гледам че има в доксигена TAGFILES - това някой ползвал ли го е за нещо, и дали има отношение?

Е за това как се ползва доксигена той си има документация и примерчета... Аз като цяло имам един проблем с него - условната компилация. Нещо не успях да я подкарам с него и затова не го и ползвам толкоз. Мисля да го ползвам само като генератор, т.е. сам да си пиша документацията и ръчно да вкарвам за парсване само определни сорсове. Но е голяма играчка и все я оставям за светлото бъдеще

Иначе макросите му бачкаха, т.е. ти може да си направиш твои тагове и те да правят каквото им кажеш, включително да слага @see и да го индиксира някъде...

Да, така ще подходя, мерси за информацията. Питах преди да задълбая за да сондирам мнения дали съм на псевдо-прав път...
А за условното компилиране съм виждал някъде да слагат:

За да включват изрично парчета когато "билдва" доксигена. Но то имало и доста други възможности в тая посока, вкл. пълно забраняване на препроцесинга:
https://stackoverflow.com/questions/26043007/make-doxygen-doxument-the-ifdef-parts-too
http://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html

ЕДИТ: Чукча писател, не читател ... на второ четене ти схванах идеята, но няма да си трия коментара, че все пак може да е от полза

И на мен ми е малко трудно да проследя нишката - доколкото сханах имаш да решаваш 2 проблема:

1) Как да стигнеш от съобщение за грешка в лог-а до съответния сорс който го е изгенерирал - това е лесно, ползваш addr2line и т.н. - трябва ти разбира се error log db, build система, source control (git) сървър и т.н. + отгоре нещо което да навърже всичко - т.е. за всяка грешка в лог-а да изкара от буилд системата съответната дебъг информация за да получи име на сорс файл и линия и после да изкара от сорс контрола съответната ревизия на сорса и да ти покаже текст-а - съответно това е хубаво да е гарнирано с приятен за човека графичен интерфейс (веб?)

2) Как да стигнеш от сорса до съответния външен документ в който е описано - задание, грешка или квото там е причината за да се напише този сорс - тук варианти също колкото искаш - github имат добро нещо - в коментар слагаш референция към със @, # и т.н. - виж им в markdown какво точно може - само, че за това трябва да хостваш сорса си при тях. И все пак цялостната интеграция на работният процес е доста компромисна все още. Аз бих погледнал gitlab - можеш да го хостнеш при себе си и като бонус с него идва и CI т.е. буилд система.

Сега се сещам, че в предната фирма където всичко беше организирано почти перфектно в това отношение ползвахме още един подход - git blame - с него за всяка промяна в сорса можеш да видиш с кой комит е направена - разбирай за всяка отделна линия. В самото комит съобщение колегата беше направил правила да започва винаги със номера на issue-то и не можеше да добавиш нищо без да има issue в което да се описват всичко. Ползвахме redmine но сега като, че ли бих ползвал негов форк - https://www.openproject.org/ - това дори води колко часа си работил по даден комит и съответно може да фактурира на крайния клиент

Та да обобщя:

git (hub/lab), jenkins, redmine, reviewboard - всичкото това може да се наинтегрира в една цяла система - ще взема да се видя с предния шеф - беше ми подметнал, че ако имам мерак може да ми даде сорсовете да опън сорснем всичко по темата

gicho, под "условно компилиране" имам предвид логика, която определя кои сорс файлове и как да се компилират.

Просто понятието "проект" при мен е малко относително. В смисъл всички сорсове са ми в един общ кюп. От него по определена логика се компилира един или друг проект.
Но организацията на кюпа няма нищо общо с даден проект. В кюпа има всичко и е подредено по логиката на кюпа. Примерно неща, които касаят архитектурата на ядрото са в папки за М0, М3 и т.н. Неща които касаят производители са си по производители, стековете са си по стекове, драйверите са си по тяхната логика и т.н. Целта е да няма дублиране на код и си е систематизирано по някакъв начин.
Проблемът е че не може просто така да тръгнеш да обработваш сорсовете. Примерно има хедъри с едни и същи имена, имам структури с едни и същи имена, функции с едни и същи имена. При компилация си имам система и тя определя кой точно хедър ще се ползва, кои сорсове и всичките дублации и конфликти се изчистват. Говоря за мейкфайл система. Но доксиген не ползва make и логиката ми увисва... То и без друго логиката трябва да е различна, понеже за компилация са нужни само определени неща, докато при документацията е редно всичко да се е документирано.

Но така или иначе не открих вариант за някакъв вид логика на тема условно компилиране. Освен ръчно да си пиша документацията

Ясно че не ти е приоритет да го мислиш сега, но проблем ли е "configure" стъпката ти да подготвя изчистените сорсове - пък ако ще и копие в друга папка, и после там да пускаш доксигена?
Иначе има разни тактики да се "закачиш" към билд-а и така да хванеш кои файлове за пипнати от гцц-то при конкретния билд - има един static code анализатор - pvs-studio. Там пускаш един страничен процес (като администратор) и той дебне "ефира" - ако види създаване на процес с подходящо име (gcc, clang или на microsoft компилаторите) се усеща и по някакъв начин се закача на вход-изхода на gcc-то. Така хващат всичката им нужна информация и работи учудващо добре. Играх си да чекна няколко мои проекта и нямаше пропуск - единственото неудобство е че иска ръчно (или през шел команда) да му кажеш кога е приключил билда за да почне да анализира информацията. Силното е че не ти се налага да пипаш проектите изобщо и няма значение дали са мейк, еклипс, VS или каквото и да е друго.
Преди време бях гледал една билд система, ама забравих името, която за да следи зависимостите между файловете ползваше нещо подобно - като извикаш gcc за даден сорс тя се закача и прихваща кои файлове (include-и) се достъпват при компилирането. Така после знае как да прави ефективни инкрементални билдове - според тестовете времена за билдване бяха в порядъци по-бързи отколко с мейк.
При теб може да е по-лесно защото можеш лесно да инжектираш някакъв твой инструмент във пайпа - накакъв wrapper на гцц примерно.

@Palavrov - не мога да диктувам какво да бъде "горното" ниво, което управлява създаването на кода - в момента е редмайн и issue-та, което е закачено автоматично към svn клиента и при commit се добавя идентификатор на issue-то по което е работено - явно и при вас е била подобна постановката.
Само че не искам да се връзвам с определено "горно" ниво - някой екипи ползват код генератори от техни си DSL езици, други са насочени към automotive процес и там даже не им знам подхода точно, трети математически моделират и верифицират, други копаят UML, сега има едни "модни" OPC UA моделирания (много сбъркана идея ми е личното мнение), а като legacy се работи и на принципа word документи със свободно описание (текст и диаграми) т.е. спецификации, и изцяло ръчно "генериране" на кода от програмистите.
Искам да изчистя за себе си какво е общото и да направя достатъчно независимо решение. Иначе гитхъб процеса ми допада много като концепция, но е неприемлив за нашия бизнес модел и няма да стане. Да не говорим че дори и да става нещо трудно може да се наложи, особено ако е нещо голямо и засяга много хора и нива едновременно. Та гледам да го разделя на стъпки и да отворя възможности за разширение за "съседите".

Мога лесно да го направя, но както казах логиката на компилацията и документацията трябва да е различна. Компилацията е една "извадка", докато документацията е добре да е обща т.е. да има всичко. Където има варианти е добре да се вижда какви са и т.н.



Той и еклипса има такава функционалност (макар да работи само когато си иска)...

Така или иначе проблемът с вариациите си остава. Освен това проблемът не е само как да укажа на doxygen какво да сканира. Аз винаги мога и ръчно да го пусна, но той просто НЕ може да обработва такъв тип сорсове правилно. Не е предвидено да имаш различни дефиниции на едно и също нещо. Съответно като си генерира линкове и т.н. си харесва една от дефинициите (примерно първата) и от там нататък само нея ползва или дава грешка.
Компилаторите работят по същия начин, те също очакват по една дефиниция за повечето неща. Но при компилаторите това е ОК, в смисъл ако искам 50 различни фърмуера така или иначе ще компилирам 50 пъти и всеки път различни неща. Но като документация не искам 50 различни документа. Искам една обща документация, която да включва всички сорсове. Само че doxygen-a се нааква като му подадеш взаимно изключващи се сорсове...

Аз пък смятам това не за проблем, а за желан фийчър - трябва да си има една конкретна и прецизна документация на точния вариант на продукта - иначе клиента пита туй ще не работи при мен като го пише в документацията... И трябва да му дават документ с разликите между вариантите примерно и става още работа. Да не говорим че понякога едни неща ги има само за "специални" клиенти и другите не е желателно да ги дразним с неща, които не искаме да ни искат
Както и да е, това е по-скоро въпрос на виждане и подход в конкретния процес в дадената организация и има различни критерии.

Предпочитам да имам възможност

Освен това ръководството за потребителя, ако потребителите не са програмисти, изобщо няма връзка със сорсовете и обикновено се пише отделно. Ако пък потребителите са програмисти, то най-вероятно те ще искат да променят нещо. Тия дето искат да компилират 1:1 чужд код следвайки стъпка по стъпка документацията трудно може да се нарекат "програмисти"

Генерирането на документацията не може ли да се управлява както обикновенно компилиране?
Само, че резултата няма да е изпълним файл а документация - съответно и компилаторът няма да е gcc а там нещо си друго ...

Не знам мен ли питаш, но при мен проблемът ми е че доксиген се държи точно както компилатор. Демек ако нещо не може да има повече от една имплементация на Ц/Ц++ то и в доксиген не може. А би трябвало да е както в Еклипса да кажем. Там колкото имплементации имаш - толкова. Всичките се индексират. И ако искаш да отидеш на дефиницията на нещо с повече варианти (F3) просто те пита на кой вариант искаш да отидеш. Не те мята на първия случаен, нито те псува че са повече от един вариантите.

Не питам конкретно а по скоро мисля на глас ... във въпросителна форма

Гичо, те това не ти ли върши работа?

https://stackoverflow.com/a/6171650/168872

Нещо такова търся, ама не смея да отговоря на въпроса ти с твърдо "да" понеже не съм сигурен че е точно това
Искам там в сорса да туря маркер някакъв, който да е уникален - линк към уникално място върши работа на пръв поглед. Колебанията ми са дали такъв вид идентификатор (линк, URL, URI) е оптималното, или трябва да е нещо скаларно, или пък да е нещо свързано с контекста - например комбинация от идентификатор (0, 1, 2, 3...) и "контекст" в смисъл __FILE_+идентификатор, или __FUNCTION__+__COUNTER__. Или пък трябва да е нещо "глобално" и да няма дублиране във всички сорсове.
Use case-ове на тази щуротия би трябвало да са:
- 1. В C кода е сложен този идентификатор понеже от по-високото ниво, при транслиране/код генериране е изгенериран някакъв ред/блок от C изрази и е полезно после при четенето (или дебъгване) на кода да може да се направи обратната връзка към модела или спецификацията
- 2. При "ръчен" дизайн програмиста е измислил някакъв бисер, написал го е на C и иска да "документира" произведението си - т.е. да измисли някакъв документ (мета-данни) и в изблик на нестихващо самодоволство да ги "линкне" към C кода си
И двета се покриват от "линк" идеята, но то това е донякъде зависимо от функционалността която се крие зад правилата за описване и работа с тоя линк. Ако приемем че там на полето "линк" стои някакъв псевдо-свободен текст значи можем да опишем достатъчно свободно каквото си поискаме, без да го "ембедваме" цялото вътре.
Всъщност тоя идентификатор/текст/URL е локален в дадения сорс или проект - имам предвид че може да се генерира нещо като PROJECT_identificator, т.е. тия идентификатори да мога да се дефинират в namespace - например отделен за всеки проект, или за всеки отдел във фирмата, или за всяка продуктова линия, или възложител, или пък глобален (за фирмата).

Мисля че си поизчистих концепцията в главата, ще действам по същество.