Микроконтролери и електроника
http://mcu-bg.com/mcu_site/

doxygen проблеми (и решения?)
http://mcu-bg.com/mcu_site/viewtopic.php?f=7&t=15186		 Страница 1 от 1
Автор:  miro_atc [ Пон Апр 10, 2017 10:43 am ]
Заглавие:  doxygen проблеми (и решения?)
Навремето се бях опитал и го зарязах, сега пак ме засърбя, че на пръв поглед е добре като идея, ама като закопая и все удрям на камък...

Значи имам няколко принципни проблема и не знам как да ги реша...

Първо искам да посъкратя малко генерираната информация. Идеята да се документира всяка променлива и всяка функцийка е правилна по принцип. Така трябва да е в сорс кода. Обаче в една документация това е абсурдно и меко казано безполезно. Примерно за една проста периферия аз имам хедър с една структура от регистрите плюс define-и за стойностите им. Самият h-файл е 2-3 странички текст. Като пусна doxygen-а то бълва 20-30 страници. Нито е по-прегледно нито нищо...

Вторият сериозен проблем е с вариациите на проектите. Много често имам "алтернативни" сорсове. Примерно за cortex-m0 и за cortex-m3. Функциите са едни и същи, просто имплементирани за различни ядра. С техники като условно компилиране се ползват едните или другите сорсове. Съответно може да имам хедъри с едни и същи имена. При компилация include директориите са различни така че се ползва правилния хедър. Но в документацията няма "правилен"... трябва да се документират всички и по някакъв начин да се покаже, че това са алтернативни сорсове. Хайде аз като страници/модули мога да ги наредя някак си, обаче doxygen генерира и йерархични дръвчета и кое от къде се вика, изобщо доста картинки и става боза...

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

Имам и други проблемчета естествено, така че всякакви идеи, техники, както и примерни проектчета с добри doxygen коментари са добре дошли ;-)
Автор:  Pif [ Пон Апр 10, 2017 11:36 am ]
Заглавие:  Re: doxygen проблеми (и решения?)
Абе аз не съм програмист ама съм чувал, че тая работа не става така. Или си я прави тоя дето си е писал кода на ръка или му я прави някой студент на малка заплата дето се учи. Май в световен мащаб не е открит читав начин за туй дето го искаш.
Не ми взимай мнението на сериозно - аз код не пиша. Само де що съм чувал клюки.
Автор:  ДедоБоре [ Пон Апр 10, 2017 11:51 am ]
Заглавие:  Re: doxygen проблеми (и решения?)
отговора и на двата въпроса донякъде се решава през doxywizard-а. отдавна съм го правил и ми е малко мъгляв спомена.

през wizard-а правиш самостоятелно компилация да двата модула (М0 и М4), като ми казваш да направи и тагове (tag files) за тях.
после правиш нов мастер и в expert->external му показваш всички отделни тагове.

малко са разхвърляни чек-боксчетата, но се съобразява лесно какво да цъкнеш
Автор:  miro_atc [ Пон Апр 10, 2017 3:54 pm ]
Заглавие:  Re: doxygen проблеми (и решения?)
ще пробвам с tag-вете като понатрупам малко материал...

То и в обикновен файл имам проблем с препроцесинга... Аз не искам то да ми прави какъвто и да било препроцесинг и уж има някаква опция ENABLE_PREPROCESSING, обаче тя ако не е на YES става пълна боза.
Автор:  ДедоБоре [ Пон Апр 10, 2017 8:43 pm ]
Заглавие:  Re: doxygen проблеми (и решения?)
кой препроцесинг :D

ако е само доксигенския, има таг \cond. в командна линия му задаваш стойността на условието.

ако е С препроцесора, там също има хиляда опции - той да препроцесва, да вика външен препроцесор (gcc), а инстиския кеф е в С++.
аз понеже съм тъп железар, до тия неща не съм дорасъл.

май имаше и някакъв таг директно да редиш ТеХ сентенции
Автор:  miro_atc [ Пон Апр 10, 2017 9:07 pm ]
Заглавие:  Re: doxygen проблеми (и решения?)
Препроцесинга на doxygena...

и по специално #if-#else обработката. Нормално е в сорс кода да има неща от сорта
Код:
#if condition

   variant 1

#else
   
   variant 2

#endif

При компилация в зависимост от условието ще се ползва единия или другия вариант. При документация обаче в повечето случаи е редно да се документират и двата варианта. Особено за библеотечен код описанието за това какви варианти има е много по-важно от самия код, тъй като потребителите обикновено не се интересуват от детайлите на кода, а само как да си го настроят/ползват.
Както казах има някаква опция за изключване, ама тя първо генерира един куп warnings и второ изключва не само #if ами и #define и изобщо става такава боза, че не мога да схвана смисъла на подобна опция.
Автор:  miro_atc [ Сря Апр 12, 2017 1:24 pm ]
Заглавие:  Re: doxygen проблеми (и решения?)
брр... много зле, идва ми пак да го зарежа тва нещо :-(

Интересно как не седнаха да го оправят тоя doxygen или някаква друга алтернатива да направят... Идеята документация и сорс код да вървят заедно е прекрасна, ама и да имаше читаво тулче...
Автор:  ДедоБоре [ Сря Апр 12, 2017 1:57 pm ]
Заглавие:  Re: doxygen проблеми (и решения?)
ква мотика настъпи?

според мен доксиджена си е нормален, просто стана много сложен. ама това е тенденция с всичко, де.
или на мен ми пада IQ-то, или остарявам, или и трите (+ мързи ме да чета)
Автор:  miro_atc [ Сря Апр 12, 2017 2:24 pm ]
Заглавие:  Re: doxygen проблеми (и решения?)
Не знам... или моето IQ не е достатъчно, за да ползвам доксиген, но тотално се разминаваме.
Единственото, което що-годе ми харесва е външния вид. Като погледнеш (ако не четеш какво пише) изглежда добре. Зачетеш ли се обаче и особено пък ако знаеш какво би трябвало да бъде написано става зле...
Доколкото го схващам аз, то си очаква някакъв съвсем простичък и малък сорс и от него да изгенерира огромна боза с глупости. Никаква организация, никакво структуриране, никакво подреждане, никакви сложнотии, нищо... ниШТо :-(
А това дето раздува ми напомня как си писах дипломната и за една нощ трябваше да изсмуча колкото се може повече, та от половин страничка смислена информация успях да докарам към 100-на страници локуми ;-) Същата история ето ти ги тук са 70 сорс файлчета, от тях доксито изсмука 7000 файлав около 70 директори.. Само че аз искам да направя документация не да отварям бозаджийница :-(
Автор:  ToHu [ Чет Апр 13, 2017 5:29 am ]
Заглавие:  Re: doxygen проблеми (и решения?)
Това най-вероятно е за "програмисти" и проекти с клонящ към нула смислен собствен код който трябва да документираш и продадеш за поне 200-300 млн.
Автор:  Цецо [ Чет Апр 13, 2017 8:47 am ]
Заглавие:  Re: doxygen проблеми (и решения?)
И аз имам няколко неуспешни опита да се сработя с това животно. Е не става и не става. Дето вика Миро - като му дадеш някакъв относително прост код с що годе линейна структура - бива.

Ама ако е нещо по-завъртяно, то губя повече време да наглася доксиджена, отколкото да напиша смисления код. И накрая резултата пак е че имаш "някаква" документация, ама ако решиш да я ползваш... в крайна сметка се стига до F3->F3->F3 и Search in File в еклипса и толкова.

Хубавото на доксиджена е, че минава за достатъчен по разните му там ИСО-та. И одиторите като го видят са ОК. Ето тук документирани няколко функции, тук структурките.... достатъчно да ги направи щастливи. А отдолу, че е пълна боза...
Автор:  miro_atc [ Чет Апр 13, 2017 9:50 am ]
Заглавие:  Re: doxygen проблеми (и решения?)
Хубава идея е, но за съжаление програмирането на тия доста им куца. Направили са големи сложнотии, а в същото време елементарни неща липсват или не работят.
Аз така и не намерих читав начин да си организирам един сорс файл/модул. Рових за шаблони, примери.. йок! Аз си измислих някакъв прост шаблон, изпочупех си пръстите и клавиатурата да го разнасям по файловете и уж почти всички файлове ги направих еднотипни, но като пусна доксито единия файл изглежда по един начин, другия по друг.

Тъпото е, че реално в Еклипса по-добре се виждат нещата. Първо се вижда всичко, второ чрез подредба и коментари долу-горе има някаква структура и се вижда кое за кое се отнася. Примерно имам периферия с някаква структура с регистри, всеки регистър има определени полета/битове, които от своя страна имат определени стойности. Тия неща се виждат и само като разглеждаш с Еклипс, но има и много лесна навигация, примерно някъде из сорса се работи с периферия - F3 и отиваш на дефиницията на периферията, виждаш регистрите. Маркираш даден регистър CTRL-K и отиваш на неговите полета и т.н.
При доксигена няма нива... съответно всички #define ги плюсва в един общ кюп, маха и всякакви коментари и подредба и после ходи разбери кой #define за кое поле и кой регистър се отнася. Няма навигация, или ако я има тя е само за топ нивото. А... и целия тоя боламач може да го гледаш през няколко различни изгледа, веднъж като "модул", веднъж като сорс файл, веднъж като структури и т.н. И във всеки от тия изгледи нещо е различно или липсва, което не знам с каква цел е направено... може би с цел да те обърка още повече.

Както и да е... аз си мърморя или по-точно изпускам парата ;-) Иначе ако има някой студент или кандидат професор, това си мисля че е много подходяща тема за дипломна че даже и дисертация. С радост ще му помогна с идеи как да направи документираща система ;-)
Страница 1 от 1 Часовете са според зоната UTC + 2 часа [ DST ]
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group
http://www.phpbb.com/