bayesclasses-general

[Bayes++] Doxygen documentation

[Nicola B. <nb...@es...>]

Dear Michael,
I've just started to use Bayes++ for my project. Although after spending some 
time on your examples I've been able to implement my own simple filter, I've 
found myself a little lost in the Doxygen documentation. Then I realized that 
inside the source files (.hpp) there are much more useful comments (/* ... 
*/) than in the .html files generated by Doxygen. I wonder then if there's a 
simple way to get these comments included in the HTML documentation, which I 
think would be very useful in particular for beginners like me :)
Cheers
Nicola

-- 
------------------------------------------
Nicola Bellotto
University of Essex
Department of Computer Science
Wivenhoe Park
Colchester CO4 3SQ
United Kingdom

Room: 1N1.2.8
Tel. +44 (0)1206 874094
E-Mail: nb...@es...
URL: http://privatewww.essex.ac.uk/~nbello
------------------------------------------

[Bayes++] Doxygen documentation

[Fredrik O. <fre...@id...>]

The automatically generated Doxygen documentation for Bayes++ does not seem 
to include the comments found in the code. This is probably due to the fact 
you've written the comments between the function signature and the function 
body; while Doxygen prefers comments to be written before the function 
signatures (or after the body). You will also need to start each comment 
with double asterix' ("/**") to mark them as code-documentation.

I would gladly help you in the task of "fixing" the comments to comply with 
Doxygen if you're interested in any help.

A simple example of Doxygen code-comments can be found on
http://www.stack.nl/~dimitri/doxygen/docblocks.html

regards,
Fredrik Orderud
Ph.D student in Computer Science, NTNU 

[Bayes++] Re: Doxygen documentation

[Michael S. <ma...@mi...>]

Hello Fredrick.

On Sunday 25 Sep 2005 23:02, Fredrik Orderud wrote:
> The automatically generated Doxygen documentation for Bayes++ does not seem
> to include the comments found in the code. This is probably due to the fact
> you've written the comments between the function signature and the function
> body; while Doxygen prefers comments to be written before the function
> signatures (or after the body). You will also need to start each comment
> with double asterix' ("/**") to mark them as code-documentation.

I started work on some experimental Doxygen comments once before. It didn't 
get very far. There are still some /** comments in unsFlt.xpp.

Apart from the time required I came across two problems.
a) Many of the member functions group naturally together. In the resulting 
documentation I wanted to keep this grouping. That is with a function 
declerations followed by the explanitory text.

b) At the moment the comments are seperated between the .cpp and .hpp files. 
In the .hpp there are shorter interface comments related to the interface 
specification. In the .cpp files there are algorithm descriptions. I was 
never clear how I would put all this together.

> I would gladly help you in the task of "fixing" the comments to comply with
> Doxygen if you're interested in any help.

That would be very helpful and a great offer. From your previous comments I 
assume you are using code from the CVS HEAD and not one of the 2003.8 
releases.

I have been working on this code recently with the aim of putting out a new 
release based on the code in the HEAD. I have some ideas how to intergrate 
the 'by-product' work in the head with the previous interface.

The CVS HEAD also has and FAQ page. Which I think will help in the future.
Any other ideas how improve the documentation would also be great.

Thanks,
	Michael

-- 
___________________________________
Michael Stevens Systems Engineering

34128 Kassel, Germany
Phone/Fax: +49 561 5218038

Navigation Systems, Estimation  and
                 Bayesian Filtering
    http://bayesclasses.sf.net
___________________________________

Re: [Bayes++] Re: Doxygen documentation

[Fredrik O. <fre...@id...>]

----- Original Message ----- 
From: "Michael Stevens" <ma...@mi...>
To: <bay...@li...>
Sent: Tuesday, September 27, 2005 10:01 PM
Subject: [Bayes++] Re: Doxygen documentation

> I started work on some experimental Doxygen comments once before. It 
> didn't
> get very far. There are still some /** comments in unsFlt.xpp.
>
> Apart from the time required I came across two problems.
> a) Many of the member functions group naturally together. In the resulting
> documentation I wanted to keep this grouping. That is with a function
> declerations followed by the explanitory text.

You probably have to modify your comments to be either above the functions; 
or after, on the same line. It would be far easier to get into Bayes++ if 
the doxgen-doc had been improved to also include function descriptions.

> b) At the moment the comments are seperated between the .cpp and .hpp 
> files.
> In the .hpp there are shorter interface comments related to the interface
> specification. In the .cpp files there are algorithm descriptions. I was
> never clear how I would put all this together.

You can choose which commments to use for documentation, by using "/**" in 
.cpp and "/*" in .hpp, or vice versa. But I think the .hpp commments takes 
predecence if you use "/**" in both .hpp and .cpp.

>> I would gladly help you in the task of "fixing" the comments to comply 
>> with
>> Doxygen if you're interested in any help.
>
> That would be very helpful and a great offer. From your previous comments 
> I
> assume you are using code from the CVS HEAD and not one of the 2003.8
> releases.

Yes, I've been using the CVS-code. I am, however, quite fresh when it comes 
to sourceforge-projects. I only registered recently, with username 
"orderud". How does one gain write-access to the repostories?

> I have been working on this code recently with the aim of putting out a 
> new
> release based on the code in the HEAD. I have some ideas how to intergrate
> the 'by-product' work in the head with the previous interface.
>
> The CVS HEAD also has and FAQ page. Which I think will help in the future.
> Any other ideas how improve the documentation would also be great.

I assume your'e talking about "Bayes++FAQ.html", which seems to be an 
improved and extended version of the FAQ on the website. The improved "noise 
coupling" answer looks like a most welcome addition, as the sourcecode is a 
bit vauge on this.

regards,
Fredrik Orderud