Гость
Целевая тема:
Создать новую тему:
Автор:
Форумы / C++ [игнор отключен] [закрыт для гостей] / Написание документации dOxygen / 21 сообщений из 21, страница 1 из 1
17.02.2014, 19:06
    #38563565
PitBull
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
Всем доброго времени суток.

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

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

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

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

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

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

Извините, я в начале не уточнил. Соль в том, что мне надо писать доки таким образом, чтобы по ним потом сгенерировать документацию для заказчика. Заказчик требует документацию, чтобы каждый метод был задокументирован =((
...
Рейтинг: 0 / 0
19.02.2014, 19:12
    #38566705
Basil A. Sidorov
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
Литературное программирование
Правда, надо учитывать уровень и сферу деятельности автора.
...
Рейтинг: 0 / 0
19.02.2014, 23:29
    #38566877
Alex the coder
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
PitBull, если правильно понял вопрос, то я особо не парюсь пока: все функции/классы/переменные класса в хэдерах описываю с @brief/@note/@todo и мелочью вроде @a, но без спец-тегов аля fn. Реализация интерфейсов - с помощью блока с @name. На сам хэдер @file/@author с подробным описанием. Давно не пробовал, но вроде и так генерится приличная документация.
В исходниках - обычные комментарии-простыни в большом количестве ну и @file опять же.
Начальство считает, что в тяжком труде комментирования лучше перестраховаться :) В принципе особо глаз не раздражают эти самые простыни. А вот нервы здорово экономит, когда нужно править хитрый алгоритм годовалой давности.
P.S. Ну и плюс ссылки на требования из ТЗ здорово помогают, но это уже собственная разработка, к доксигену отношения не имеющая.
...
Рейтинг: 0 / 0
21.02.2014, 20:48
    #38569154
Lepsik
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
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
26.02.2014, 22:47
    #38573584
tchingiz
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
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
26.02.2014, 22:54
    #38573587
tchingiz
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
искренне_уважаемый_Репликант IMHO это бесполезное и порочное занятие писать комментарии в программных текстах. Хотя это, конечно, если нет визуальных моделей, например, тех же диаграмм деятельности или взаимодействия, к-рые описывают все взаимодействия между объектами и создаются при полноценном ООАП-подходе, например, как в RUP
совершенно дурацкое утверждение.
В идеальном случае, который лично мне не удавалось достичь /*в силу лени и не получения в свое время нужных навыков*/.
Где то на шаге проектирования хорошо бы, чтобы было описание приложения на
языке формальных спецификаций и этот текст вполне может служить комментариями
в хедерах.
...
Рейтинг: 0 / 0
26.02.2014, 22:55
    #38573588
tchingiz
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
картинки для начальства и наглядности должны создаваться как побочный продукт
от аски текста языка формальных спецификаций.
...
Рейтинг: 0 / 0
26.02.2014, 23:03
    #38573591
egorych
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
tchingizискренне_уважаемый_Репликант IMHO это бесполезное и порочное занятие писать комментарии в программных текстах. Хотя это, конечно, если нет визуальных моделей, например, тех же диаграмм деятельности или взаимодействия, к-рые описывают все взаимодействия между объектами и создаются при полноценном ООАП-подходе, например, как в RUP совершенно дурацкое утверждение.вот согласен ))
И, помимо всего прочего, нарисовать все диаграммы, необходимые для проекта даже средней сложности занимает такое количество времени, что мама не горюй. А потом нудно это, ведь, диаграмки рисовать, куда приятней писать код )))
...
Рейтинг: 0 / 0
26.02.2014, 23:15
    #38573597
tchingiz
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
egorych,
эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных?
...
Рейтинг: 0 / 0
26.02.2014, 23:18
    #38573599
tchingiz
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
ну типа так
Код: 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
26.02.2014, 23:20
    #38573600
tchingiz
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
ой блин, сорри
White Owl, MasterZiv, mayton
в спойлер возьмите плиз
...
Рейтинг: 0 / 0
26.02.2014, 23:41
    #38573615
egorych
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
tchingizegorych,
эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных?не помню, честно ((
...
Рейтинг: 0 / 0
27.02.2014, 01:17
    #38573647
egorych
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
tchingizegorych,
эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных? вспомнил , оно?
...
Рейтинг: 0 / 0
27.02.2014, 01:35
    #38573654
tchingiz
Участник
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Написание документации dOxygen
схемаспай. Два раза забывал её попробовать.

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

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


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