LINUX.ORG.RU
Форум — Development  

Система документирования


0

0

Кто какую систему документирования использует? Ибо документирование требуется, а что использовать - не знаю. Пробовал Doxygen, но возможно что-то ниасилил в настройке - получил "Warning: documented function `<тут идёт имя функции>' was not defined." для всех функций проекта. Может кто-то с таким сталкивался?

Ну или посоветуйте хорошую систему документирования. Заранее спасибо.

★★★★★
← Отображение числовых значений
exec и вывод →

Я использую doxygen + dot и для *NIX и для Windows.
Никаких особых проблем не замечал.
Может приведешь примет документированного кода?

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

Код пока толком не документирован, но при EXTRACT_ALL = YES Doxygen вроде должен выдирать и прототипы недокументированных компонентов (классов, методов и т.д.). Он этого не делает, и ругается как описывал выше.

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

> Код пока толком не документирован, но при EXTRACT_ALL = YES Doxygen вроде должен выдирать и прототипы недокументированных компонентов (классов, методов и т.д.). Он этого не делает, и ругается как описывал выше.

тестовый пример кода, который бы показывал указанное поведение в студию. а так, трудно сказать что-то вразумительное.

// wbr

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

Пожалуйста:

---------========== Doxyfile ==========---------
PROJECT_NAME           = TEST
PROJECT_NUMBER         = 1
OUTPUT_DIRECTORY       = doc
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = NO
INPUT                  = src
FILE_PATTERNS          = *.cpp *.hpp
RECURSIVE              = YES

---------========== src/test.hpp ==========---------
#ifndef __TEST_HPP
#define __TEST_HPP

#include <QWidget>

namespace TEST1
{
    namespace SubTest1
    {
	class Class1 : public QWidget
	{
	    Q_OBJECT
	public:
	    Class1(QWidget * parent = NULL) : QWidget(parent) {};
	    ~Class1() {};
	    
	    void Test1();
	    void Test2();
	    
	private:
	    QWidget * test;
	};
    };
};

#endif

---------========== src/test.cpp ==========---------
#include <test.hpp>

namespace TEST1
{
    namespace SubTest1
    {
	void Class1::Test1()
	{
	};
	
	void Class1::Test2()
	{
	};
    };
};

---------========== src/test2/test2.hpp ==========---------
#ifndef __TEST2_HPP
#define __TEST2_HPP

#include <QWidget>

namespace TEST2
{
    namespace SubTest1
    {
	class Class1 : public QWidget
	{
	    Q_OBJECT
	public:
	    Class1(QWidget * parent = NULL) : QWidget(parent) {};
	    ~Class1() {};
	    
	    void Test1();
	    void Test2();
	    
	private:
	    QWidget * test;
	};
    };
};

#endif

---------========== src/test2/test2.cpp ==========---------
#include <test2.hpp>

namespace TEST2
{
    namespace SubTest1
    {
	void Class1::Test1()
	{
	};
	
	void Class1::Test2()
	{
	};
    };
};

---------========== doxygen.log ==========---------
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for files to exclude
Searching for files to process...
Reading and parsing tag files
Notice: Output directory `doc' does not exist. I have created it for you.
Preprocessing /home/sectoid/documents/devel/test/src/test.cpp...
Parsing file /home/sectoid/documents/devel/test/src/test.cpp...
Preprocessing /home/sectoid/documents/devel/test/src/test.hpp...
Parsing file /home/sectoid/documents/devel/test/src/test.hpp...
Preprocessing /home/sectoid/documents/devel/test/src/test2/test2.cpp...
Parsing file /home/sectoid/documents/devel/test/src/test2/test2.cpp...
Preprocessing /home/sectoid/documents/devel/test/src/test2/test2.hpp...
Parsing file /home/sectoid/documents/devel/test/src/test2/test2.hpp...
Building group list...
Building directory list...
Building namespace list...
Building file list...
Searching for included using directives...
Building class list...
Associating documentation with classes...
Computing nesting relations for classes...
Searching for members imported via using declarations...
Building example list...
Searching for documented variables...
Building member list...
Searching for friends...
Searching for documented defines...
Computing template instances...
Flushing cached template relations that have become invalid...
Creating members for template instances...
Computing class relations...
Searching for enumerations...
Searching for member function documentation...
/home/sectoid/documents/devel/test/src/test.cpp:8: Warning: documented function `void TEST1::SubTest1::Class1::Test1' was not defined.
/home/sectoid/documents/devel/test/src/test.cpp:12: Warning: documented function `void TEST1::SubTest1::Class1::Test2' was not defined.
/home/sectoid/documents/devel/test/src/test2/test2.cpp:8: Warning: documented function `void TEST2::SubTest1::Class1::Test1' was not defined.
/home/sectoid/documents/devel/test/src/test2/test2.cpp:12: Warning: documented function `void TEST2::SubTest1::Class1::Test2' was not defined.
Building page list...
Search for main page...
Computing page relations...
Determining the scope of groups...
Sorting lists...
Freeing entry tree
Determining which enums are documented
Computing member relations...
Building full member lists recursively...
Adding members to member groups.
Computing member references...
Inheriting documentation...
Generating disk names...
Adding source references...
Adding todo/test/bug list items...
Generating style sheet...
Counting data structures...
Resolving user defined references...
Combining using relations...
Finding anchors and sections in the documentation...
Generating index page...
Generating example documentation...
Generating file sources...
Generating code for file src/test.hpp...
Generating code for file src/test2/test2.hpp...
Generating file documentation...
Generating docs for file src/test.cpp...
Generating docs for file src/test.hpp...
Generating docs for file src/test2/test2.cpp...
Generating docs for file src/test2/test2.hpp...
Generating page documentation...
Generating group documentation...
Generating group index...
Generating class documentation...
Generating annotated compound index...
Generating hierarchical class index...
Generating member index...
Generating namespace index...
Generating docs for namespace TEST1
Generating docs for namespace TEST1::SubTest1
Generating docs for namespace TEST2
Generating docs for namespace TEST2::SubTest1
Generating namespace member index...
Generating graph info page...
Generating file index...
Generating example index...
Generating file member index...
Generating page index...

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


версия doxygen? uname -a? что-то еще особенное?

у меня с указанными примерами и файлом настроек doxygen прекрасно генерит документацию на WinXP + Doxygen 1.4.6 [родная сборка] или NetBSD 3.x + Doxygen 1.4.7:


--- WinXP --
$ doxygen --version
1.4.6-NO

$ doxygen Doxyfile
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for files to exclude
Searching for files to process...
Reading and parsing tag files
Preprocessing C:/Temp/foo/src/test.cpp...
Parsing file C:/Temp/foo/src/test.cpp...
Preprocessing C:/Temp/foo/src/test.hpp...
Parsing file C:/Temp/foo/src/test.hpp...
Preprocessing C:/Temp/foo/src/test2.cpp...
Parsing file C:/Temp/foo/src/test2.cpp...
Preprocessing C:/Temp/foo/src/test2.hpp...
Parsing file C:/Temp/foo/src/test2.hpp...
Building group list...
Building directory list...
Building namespace list...
Building file list...
Searching for included using directives...
Building class list...
Associating documentation with classes...
Computing nesting relations for classes...
Searching for members imported via using declarations...
Building example list...
Searching for documented variables...
Building member list...
Searching for friends...
Searching for documented defines...
Computing template instances...
Flushing cached template relations that have become invalid...
Creating members for template instances...
Computing class relations...
Searching for enumerations...
Searching for member function documentation...
Building page list...
Search for main page...
Computing page relations...
Determining the scope of groups...
Sorting lists...
Freeing entry tree
Determining which enums are documented
Computing member relations...
Building full member lists recursively...
Adding members to member groups.
Computing member references...
Inheriting documentation...
Generating disk names...
Adding source references...
Adding todo/test/bug list items...
Generating style sheet...
Counting data structures...
Resolving user defined references...
Combining using relations...
Finding anchors and sections in the documentation...
Generating index page...
Generating file index...
Generating example documentation...
Generating file sources...
Generating code for file src/test.hpp...
Generating code for file src/test2.hpp...
Generating file documentation...
Generating docs for file src/test.cpp...
Generating docs for file src/test.hpp...
Generating docs for file src/test2.cpp...
Generating docs for file src/test2.hpp...
Generating class documentation...
Generating annotated compound index...
Generating hierarchical class index...
Generating member index...
Generating page documentation...
Generating group documentation...
Generating namespace index...
Generating docs for namespace TEST1
Generating docs for namespace TEST1::SubTest1
Generating docs for compound TEST1::SubTest1::Class1...
Generating docs for namespace TEST2
Generating docs for namespace TEST2::SubTest1
Generating docs for compound TEST2::SubTest1::Class1...
Generating group index...
Generating example index...
Generating file member index...
Generating namespace member index...
Generating page index...
Generating graph info page...
--- WinXP --

на выходе имеем http://ianzag.megasignal.com/tmp/doxygen/win32/doc/

--- NetBSD ---
$ doxygen --version
1.4.7

$ doxygen Doxyfile
Notice: Output directory `doc' does not exist. I have created it for you.
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for files to exclude
Searching for files to process...
Reading and parsing tag files
Preprocessing /tmp/foo/src/test.cpp...
Parsing file /tmp/foo/src/test.cpp...
Preprocessing /tmp/foo/src/test.hpp...
Parsing file /tmp/foo/src/test.hpp...
Preprocessing /tmp/foo/src/test2.cpp...
Parsing file /tmp/foo/src/test2.cpp...
Preprocessing /tmp/foo/src/test2.hpp...
Parsing file /tmp/foo/src/test2.hpp...
Building group list...
Building directory list...
Building namespace list...
Building file list...
Searching for included using directives...
Building class list...
Associating documentation with classes...
Computing nesting relations for classes...
Searching for members imported via using declarations...
Building example list...
Searching for documented variables...
Building member list...
Searching for friends...
Searching for documented defines...
Computing template instances...
Flushing cached template relations that have become invalid...
Creating members for template instances...
Computing class relations...
Searching for enumerations...
Searching for member function documentation...
Building page list...
Search for main page...
Computing page relations...
Determining the scope of groups...
Sorting lists...
Freeing entry tree
Determining which enums are documented
Computing member relations...
Building full member lists recursively...
Adding members to member groups.
Computing member references...
Inheriting documentation...
Generating disk names...
Adding source references...
Adding todo/test/bug list items...
Generating style sheet...
Counting data structures...
Resolving user defined references...
Combining using relations...
Finding anchors and sections in the documentation...
Generating index page...
Generating example documentation...
Generating file sources...
Generating code for file src/test.hpp...
Generating code for file src/test2.hpp...
Generating file documentation...
Generating docs for file src/test.cpp...
Generating docs for file src/test.hpp...
Generating docs for file src/test2.cpp...
Generating docs for file src/test2.hpp...
Generating page documentation...
Generating group documentation...
Generating group index...
Generating class documentation...
Generating annotated compound index...
Generating hierarchical class index...
Generating member index...
Generating namespace index...
Generating docs for namespace TEST1
Generating docs for namespace TEST1::SubTest1
Generating docs for compound TEST1::SubTest1::Class1...
Generating docs for namespace TEST2
Generating docs for namespace TEST2::SubTest1
Generating docs for compound TEST2::SubTest1::Class1...
Generating namespace member index...
Generating graph info page...
Generating file index...
Generating example index...
Generating file member index...
Generating page index...
--- NetBSD ---

на выходе имеем http://ianzag.megasignal.com/tmp/doxygen/netbsd/doc/

// wbr

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

sectoid@mobility ~/documents/devel/test $ uname -a
Linux mobility 2.6.17-gentoo-r5 #2 PREEMPT Wed Sep 6 22:13:32 EEST 2006 i686 Intel(R) Celeron(R) M processor 1500MHz GenuineIntel GNU/Linux

sectoid@mobility ~/documents/devel/test $ doxygen --version
1.4.7

Бока в gentoo?...

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

> sectoid@mobility ~/documents/devel/test $ uname -a
Linux mobility 2.6.17-gentoo-r5 #2 PREEMPT Wed Sep 6 22:13:32 EEST 2006 i686 Intel(R) Celeron(R) M processor 1500MHz GenuineIntel GNU/Linux
> sectoid@mobility ~/documents/devel/test $ doxygen --version
1.4.7

версии вроде вполне нормальные, по крайней мере, я не вижу протеворечий.

> Бока в gentoo?...

не знаю, может быть :-/ могу лишь посоветовать для проверки пустить его на win32 и посмотреть :)

ну ладно, бог с ними, с предупреждениями. в конце-концов, если это просто warning-и то и плевать. сама то документация в doc/html нормально генерится?

// wbr

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

УРА! Проблема решена! Всё дело было в том, что Doxygen был собран с "-O3". От этого его и глючило. Лечится пересборкой с default-параметрами оптимизации.

Всем спасибо за помощь. Тема закрыта.

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

К тому, что отдельные адепты компиляют все и вся с -O3, подобно настоящим джедаям, не боящимся косяков и глюков.

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

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

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

Обычно при разгоне от стабильности к нестабильности идут, а не наоборот.

e
()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.
← Отображение числовых значений
Development
exec и вывод →