powered by simpleCommunicator - 2.0.59     © 2025 Programmizd 02
Целевая тема:
Создать новую тему:
Автор:
Закрыть
Цитировать
Форумы / C++ [игнор отключен] [закрыт для гостей] / Написание документации dOxygen
21 сообщений из 21, страница 1 из 1
Написание документации dOxygen
    #38563565
PitBull
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Всем доброго времени суток.

Хотел спросить, кто-как пишет доки по коду? К слову хорошее обсуждение получится.

Сам хотел заюзать стиль из моей любимой Qt, но там описание какое-то странное - иногда они используют тег \fn, иногда нет. Что мне очень нравится - нет описания в h файле, тем самым они не замусоривают его. А вот в cpp - не на все методы есть описание, иногда оно идёт сразу за методом, иногда через \fn. Может кто поделится своей практикой ?
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38563571
Фотография MasterZiv
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Я лично пользовался doxygen-ом. Не очень активно.
Потому что я не очень верю в документацию на код.

Ещё писал в ворде документы с описанием функций.
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38563576
Фотография MasterZiv
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Ещё писал модели в UML. И генерировал документацию по ним.
Модели, естественно, были "сквозные", т.е. поддерживались во всё время разработки, и строились ещё до разработки.
Т.е. модели были всегда первичны, код только вместе с моделью менялся.
Так делал примерно проектов 5.
Очень хорошо.
Всё умерло со смертью Rose.
(Rose как бы жива, только переродилась, и как ею теперь пользоваться -- не понятно).
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38563794
egorych
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PitBull,
пользуюсь доксигеном, вот с этим утверждением не согласен:
PitBullЧто мне очень нравится - нет описания в h файле, тем самым они не замусоривают егохидер - это декларация, там самое место описанию, чего, собственно, делает код. Когда пришло время заглядывать в .cpp то значит надо уже читать собственно код, а не его описание. Из за этой неприятной привычки норвежских самоделкиных проводил лишние долгие часы в отладке, в своё время.
А любой современный редактор кода метит комментарии отдельным цветом, а некоторые, особо продвинутые, позволяют их свернуть, есичё ))
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38565686
PitBull
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
egorychPitBull,
пользуюсь доксигеном, вот с этим утверждением не согласен:
PitBullЧто мне очень нравится - нет описания в h файле, тем самым они не замусоривают егохидер - это декларация, там самое место описанию, чего, собственно, делает код. Когда пришло время заглядывать в .cpp то значит надо уже читать собственно код, а не его описание. Из за этой неприятной привычки норвежских самоделкиных проводил лишние долгие часы в отладке, в своё время.
А любой современный редактор кода метит комментарии отдельным цветом, а некоторые, особо продвинутые, позволяют их свернуть, есичё ))

хм, а если посмотреть на эту проблему по другому - если вы разработчик - открывайте документацию и читайте что делает код, но при этом методы часто называются интуитивно понятно, но и h файл не раздут, что сильно упрощает его чтение, ну а за деталями в доки?
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38565775
egorych
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PitBullхм, а если посмотреть на эту проблему по другому - если вы разработчик - открывайте документацию и читайте что делает код, но при этом методы часто называются интуитивно понятно, но и h файл не раздут, что сильно упрощает его чтение, ну а за деталями в доки?методы с интуитивно понятными названиями не требуют и больших комментариев, к примеру:
Код: plaintext
1.
2.
//! возврат базовой абстрактной модели
QAbstractModel *model() const;

ну и сильно такие комментарии перегрузят хидер?
Вся соль как раз в тех методах, которые не обладают интуитивно понятным названием, содержат неочевидный/сложный алгоритм, или имеют внутри побочные эффекты, вот их и надо документировать подробно, и желательно, имхо, там же, где находится их декларация. Потому что иногда удобно заглядывать в доку, довольно часто - в хидер, а уж совсем иногда, когда уже нет другого выбора - то в код.
...и тут вдруг ты обнаруживаешь, что есть комментарий, который кто-то забыл пометить тегом и он не попал в доку =))
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38565839
PitBull
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
egorychPitBullхм, а если посмотреть на эту проблему по другому - если вы разработчик - открывайте документацию и читайте что делает код, но при этом методы часто называются интуитивно понятно, но и h файл не раздут, что сильно упрощает его чтение, ну а за деталями в доки?методы с интуитивно понятными названиями не требуют и больших комментариев, к примеру:
Код: plaintext
1.
2.
//! возврат базовой абстрактной модели
QAbstractModel *model() const;

ну и сильно такие комментарии перегрузят хидер?
Вся соль как раз в тех методах, которые не обладают интуитивно понятным названием, содержат неочевидный/сложный алгоритм, или имеют внутри побочные эффекты, вот их и надо документировать подробно, и желательно, имхо, там же, где находится их декларация. Потому что иногда удобно заглядывать в доку, довольно часто - в хидер, а уж совсем иногда, когда уже нет другого выбора - то в код.
...и тут вдруг ты обнаруживаешь, что есть комментарий, который кто-то забыл пометить тегом и он не попал в доку =))

Извините, я в начале не уточнил. Соль в том, что мне надо писать доки таким образом, чтобы по ним потом сгенерировать документацию для заказчика. Заказчик требует документацию, чтобы каждый метод был задокументирован =((
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38566705
Basil A. Sidorov
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Литературное программирование
Правда, надо учитывать уровень и сферу деятельности автора.
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38566877
Alex the coder
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PitBull, если правильно понял вопрос, то я особо не парюсь пока: все функции/классы/переменные класса в хэдерах описываю с @brief/@note/@todo и мелочью вроде @a, но без спец-тегов аля fn. Реализация интерфейсов - с помощью блока с @name. На сам хэдер @file/@author с подробным описанием. Давно не пробовал, но вроде и так генерится приличная документация.
В исходниках - обычные комментарии-простыни в большом количестве ну и @file опять же.
Начальство считает, что в тяжком труде комментирования лучше перестраховаться :) В принципе особо глаз не раздражают эти самые простыни. А вот нервы здорово экономит, когда нужно править хитрый алгоритм годовалой давности.
P.S. Ну и плюс ссылки на требования из ТЗ здорово помогают, но это уже собственная разработка, к доксигену отношения не имеющая.
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38569154
Lepsik
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PitBullВсем доброго времени суток.

Хотел спросить, кто-как пишет доки по коду?

как-то так

Код: plaintext
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
    /**
        *  wrapper around EncodeRangeRaw with __int32 base for matissa
        *  should be called if arithmetic coding can be applyed - header.bits should less then 23 bit
        *
        *  @param [in\out] bufferSize       length of packed mantissa (in bytes)
        *  @param [in]     header           info about copmpression parameters.  must have size of allocated or size of compressed buffer
        *
        *  @return true if successfull
        */
    virtual bool EncodeMantissa( size_t& bufferSize, FloatHeader_t& header );
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573584
Фотография tchingiz
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
PitBullВсем доброго времени суток.

Хотел спросить, кто-как пишет доки по коду? К слову хорошее обсуждение получится.

Сам хотел заюзать стиль из моей любимой Qt, но там описание какое-то странное - иногда они используют тег \fn, иногда нет. Что мне очень нравится - нет описания в h файле, тем самым они не замусоривают его. А вот в cpp - не на все методы есть описание, иногда оно идёт сразу за методом, иногда через \fn. Может кто поделится своей практикой ?

вот так писал в 200x году,
http://agp1.hx0.ru/software/mlc.txt
сделал конвертор старого документатора, на котором описана эта система, в латех.
Теперь пишу на латехе. Разделы стараюсь к госту приближать, там все по теме.

Введение в доксижен когда то для журнала hDrummer-а написал.
http://agp1.hx0.ru/articles/dgIntro.pdf

Эта пояснительная записка к проекту на QT
http://agp1.hx0.ru/articles/pCst.pdf



пысы это старые обсуждения данной темы.

http://www.sql.ru/forum/32728/proektnaya-dokumentaciya-teo-tz-tp-soderzhanie-metody-i-sredstva?hl=???????????? ?????????

http://www.sql.ru/forum/23646-1/kto-kak-pishet-dokumentaciu-k-svoim-netlenkam?hl=?????????
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573587
Фотография tchingiz
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
искренне_уважаемый_Репликант IMHO это бесполезное и порочное занятие писать комментарии в программных текстах. Хотя это, конечно, если нет визуальных моделей, например, тех же диаграмм деятельности или взаимодействия, к-рые описывают все взаимодействия между объектами и создаются при полноценном ООАП-подходе, например, как в RUP
совершенно дурацкое утверждение.
В идеальном случае, который лично мне не удавалось достичь /*в силу лени и не получения в свое время нужных навыков*/.
Где то на шаге проектирования хорошо бы, чтобы было описание приложения на
языке формальных спецификаций и этот текст вполне может служить комментариями
в хедерах.
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573588
Фотография tchingiz
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
картинки для начальства и наглядности должны создаваться как побочный продукт
от аски текста языка формальных спецификаций.
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573591
egorych
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
tchingizискренне_уважаемый_Репликант IMHO это бесполезное и порочное занятие писать комментарии в программных текстах. Хотя это, конечно, если нет визуальных моделей, например, тех же диаграмм деятельности или взаимодействия, к-рые описывают все взаимодействия между объектами и создаются при полноценном ООАП-подходе, например, как в RUP совершенно дурацкое утверждение.вот согласен ))
И, помимо всего прочего, нарисовать все диаграммы, необходимые для проекта даже средней сложности занимает такое количество времени, что мама не горюй. А потом нудно это, ведь, диаграмки рисовать, куда приятней писать код )))
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573597
Фотография tchingiz
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
egorych,
эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных?
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573599
Фотография tchingiz
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
ну типа так
Код: plaintext
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
106.
107.
108.
109.
110.
111.
112.
113.
114.
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
135.
136.
137.
138.
139.
140.
141.
142.
143.
144.
145.
146.
147.
148.
149.
150.
151.
152.
153.
154.
155.
156.
157.
158.
159.
160.
161.
162.
163.
164.
165.
166.
167.
168.
169.
170.
171.
172.
173.
174.
175.
176.
177.
178.
179.
180.
181.
182.
183.
184.
185.
186.
187.
188.
189.
190.
191.
192.
193.
194.
195.
196.
197.
198.
199.
200.
201.
202.
203.
204.
205.
206.
207.
208.
209.
210.
211.
212.
213.
214.
215.
216.
217.
218.
//scheme                                                                               
//XLIST =                                                                              
//hide h_begin in                                                                      
//class                                                                                
//    type Item,                                                                       
//         xList = {|(tail, cur, ln): Item-list >< Item-list >< Nat:-                  
//                           exists beg: Item-list :- tail = beg ^ cur /\              
//                           len (tail) = ln                                           
//                 |}                                                                  
//    value                                                                                                                                 
//        h_begin     : Item-list >< Item-list -> Item-list                            
//        h_begin (tail, cur) is                                                       
//             let beg : Item-list :- tail = beg ^ cur in beg end                      
//                                                                                     
//        ,x_addHead  : xList >< Item  -> xList                                        
//         x_addHead ((t,c,l), i)  is                                                  
//             (<.i.>^t, c, l+1)                                                       
//                                                                                     
//        ,x_delHead  : xList        -~-> xList  >< Item                               
//         x_delHead ((t,c,l))  is                                                     
//             ( (tl t, if t = c then tl c else c end, l-1),  hd t)                    
//             pre t ~= <..>                                                           
//        ,x_addNext  : xList >< Item  -> xList                                        
//         x_addNext ((t, c, l), i) is                                                 
//             (h_begin(t,c)^<.i.>^c, <.i.>^c, l+1)                                    
//        ,x_delNext  : xList        -~-> xList  >< Item                               
//         x_delNext (t, c, l) is                                                      
//             ((h_begin(t, c) ^ <.hd c.> ^ tl tl c , tl tl c, l-1), hd tl c           
//             )                                                                       
//             pre len c > 1                                                           
//        ,x_headItem : xList        -~-> xList ><  Item                               
//         x_headItem (t, c, l) is                                                     
//             ((t, t, l), hd t)                                                       
//             pre t ~= <..>                                                           
//        ,x_nextItem : xList        -~-> xList ><  Item                               
//         x_nextItem (t, c, l) is                                                     
//             ((t, tl c, l), hd c)                                                    
//             pre c ~= <..>                                                           
//       ,x_delItem  : xList ><  Item  -> xList                                        
//        x_delItem ((t, c, l), i)  is                                                 
//             if    i isin h_begin (t, c) then                                        
//                                    /* to delete first occurence item in t*/         
//                 (let beg : Item-list  in                                            
//                      let tail : Item-list :- t = beg ^ <.i.> ^ tail /\              
//                                              i ~isin beg in                         
//                                                      beg ^ tail                     
//                      end                                                            
//                  end,                                                               
//                  c,                                                                 
//                  l-1                                                                
//                 )                                                                   
//             elsif i isin          c  then                                           
//                 (let beg : Item-list  in                                            
//                      let tail : Item-list :- t = beg ^ <.i.> ^ tail /\              
//                                              i ~isin beg in                         
//                                                      beg ^ tail                     
//                      end                                                            
//                  end,                                                               
//                  let beg : Item-list  in                                            
//                      let tail : Item-list :- c = beg ^ <.i.> ^ tail /\              
//                                              i ~isin beg in                         
//                                                      beg ^ tail                     
//                      end                                                            
//                  end,                                                               
//                  l-1                                                                
//                 )                                                                   
//             else                                                                    
//                 (t,c,l)                                                             
//             end                                                                     
//        ,x_slctItem : xList ><  Nat  -~->       Item                                 
//         x_slctItem((t,c,l), n)   is                                                 
//            t(n)                                                                     
//            pre l >= n                                                               
//          ,item : xList ><  Item -> Item                                               
//         item (x, i) is i                                                            
//end
                                                                                
#ifndef  __XLIST_H
#define  __XLIST_H

typedef struct  TList_ { 
    struct  TList_ *  tail; 
    void           *  item;
}TList_;

typedef struct  TList { 
    struct  TList_ *  tail; 
    struct  TList_ *  cur;
    ulong             len;

# ifdef __cplusplus
    TList ()                             ;
    ~TList()                             ;
    x_bool isEmpty () const              ;
    long   addHead (const void * newHed) ;
    void * delHead ()                    ;
    long   addNext (const void * newHed) ;
    void * delNext ()                    ;
    void * head    () const              ;
    void * curnt   () const              ;
    void * next    () const              ;
    void * slct    (const ulong p) const ;
    long   del     ( const void * item)  ;
# endif
     
}TList;

# ifdef __cplusplus

template <class I>
struct T_TList : TList {
 I * delHead ()                    { return (I*)TList::delHead(); }
 I * delNext ()                    { return (I*)TList::delNext(); }
 I * head    () const              { return (I*)TList::head ();   }
 I * curnt   () const              { return (I*)TList::curnt();   }
 I * next    () const              { return (I*)TList::next ();   }        
 I * slct    (const ulong p)const  { return (I*)TList::slct (p);   }
} 
;

# endif


# ifdef __cplusplus
      extern "C"    {
# endif

TList *
x_crtList (void);

TList *
x_iniList (TList *  list);

//
//            any member of list must be removed first
//
TList *
x_dstList (TList * list);


long
x_addHead  ( TList * list, const void * newHead);

void *                   // it show the deleted item
x_delHead (TList * list);



long
x_addNext  ( TList * list, const void * newNext);

void *                   // it show the deleted item
x_delNext (TList * list);



long
x_headItem(void ** item, const TList * list);

long
x_curItemL(void ** item, const TList * list);

long
x_nextItem(void ** item, const TList * list);


long
x_delItem(TList * list, const void * delItem);

void *                     // position should start with 0 as the array in C
                           // head is n, head->tail is n-1,...
x_slctItem (const TList * list, ulong position);

x_bool
x_isListEmpty (const TList * list);


//uint
//x_lenList  (const TList * list);

# ifdef __cplusplus
   }


 inline        TList:: TList  ()                    {x_iniList (this);}
 inline        TList:: ~TList ()                    {x_iniList (this);}
 inline x_bool TList:: isEmpty() const              {return x_isListEmpty(this) ;}
 inline long   TList:: addHead(const void * newHead){return x_addHead(this, newHead);}
 inline void * TList:: delHead()                    {return x_delHead(this); }
 inline long   TList:: addNext(const void * newHead){return x_addNext(this, newHead);}
 inline void * TList:: delNext()                    {return x_delNext(this); }
 inline void * TList:: head   () const              {
                                      void * rc = 0;
                                      if(x_headItem(&rc, this) != _OK)
                                          rc = 0;
                                      return rc;
                                     }
 inline void * TList:: curnt   () const              {
                                      void * rc = 0;
                                      if(x_curItemL(&rc, this) != _OK)
                                          rc = 0;
                                      return rc;
                                     }
 inline void * TList:: next  () const               {
                                      void * rc = 0;
                                      if(x_nextItem(&rc, this) != _OK)
                                          rc = 0;
                                      return rc;
                                     }
 inline void * TList:: slct  (const ulong p) const  {return x_slctItem(this,p);  }

 inline long   TList:: del   ( const void * item)   {return x_delItem(this, item); }

# endif



#endif

...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573600
Фотография tchingiz
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
ой блин, сорри
White Owl, MasterZiv, mayton
в спойлер возьмите плиз
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573615
egorych
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
tchingizegorych,
эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных?не помню, честно ((
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573647
egorych
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
tchingizegorych,
эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных? вспомнил , оно?
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573654
Фотография tchingiz
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
схемаспай. Два раза забывал её попробовать.

Программы для построения графа зависимостей

блин.
за какието два часа както началось запускаться,
но на склайте сбоит и собственно схему связей не рисует. закладка на релейшеншип пустая.
Руки не с того места ростут
...
Рейтинг: 0 / 0
Написание документации dOxygen
    #38573894
egorych
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
tchingizРуки не с того места ростутэто да, самоделкины - повсюду
...
Рейтинг: 0 / 0
21 сообщений из 21, страница 1 из 1
Форумы / C++ [игнор отключен] [закрыт для гостей] / Написание документации dOxygen
Найденые пользователи ...
Разблокировать пользователей ...
Читали форум (0):
Пользователи онлайн (0):
x
x
Закрыть


Просмотр
0 / 0
Close
Debug Console [Select Text]