asycxx-devel

[asycxx-devel] Documentation changes query

[Karthik B. <ka...@hi...>]

Hi Joe,
 I have a question for documentation of asycxx. Why is that you had put the
comments in the .cxx file ? Should we move it to .h ? The reason being you
have few more member functions which are mentioned in your .h file which
is not covered in the existing documentation you have. (refer DataBuffer
class
files).

I was successfully make my first documentation using doxygen. I can see you
have already put some doc comments for few files, should I be completing the
rest, similar to what you've done ? Is there anything I am missing here ?

-- 
Karthik

HiPro IT Solutions Pvt. Ltd.
http://hipro.co.in/

Re: [asycxx-devel] Documentation changes query

[Joe S. <js...@hi...>]

On Tue, 2009-03-17 at 00:23 +0530, Karthik Balakrishnan wrote:
> I have a question for documentation of asycxx. Why is that you had put
> the comments in the .cxx file ? Should we move it to .h ? The reason
> being you have few more member functions which are mentioned in
> your .h file which is not covered in the existing documentation you
> have. (refer DataBuffer class files).

Ideally, the 'api documentation' should be in the header files. i.e.,
anyone who wants to use the API should be looking into the header files
and not the .cxx files. So, the doxygen comments that describe the API
should be in the .h files. The .cxx files should have comments that
explain how things work. But, these comments need not go into doxygen.

> I was successfully make my first documentation using doxygen. I can
> see you have already put some doc comments for few files, should I be
> completing the rest, similar to what you've done ? Is there anything I
> am missing here ? 

Yeah, as first step, all the classes should be documented. So, if there
is missing documentation, please add it.

-- 
Joe Steeve
HiPro IT Solutions Pvt. Ltd.
http://hipro.co.in/

Re: [asycxx-devel] Documentation changes query

[Karthik B. <ka...@hi...>]

2009/3/17 Joe Steeve <js...@hi...>

> Ideally, the 'api documentation' should be in the header files. i.e.,
> anyone who wants to use the API should be looking into the header files
> and not the .cxx files. So, the doxygen comments that describe the API
> should be in the .h files. The .cxx files should have comments that
> explain how things work. But, these comments need not go into doxygen.


Alright. I got few files fixed as noted. But I wasn't sure if i was on the
right
track. I'll send you the patch file tonight/later this evening.


> Yeah, as first step, all the classes should be documented. So, if there
> is missing documentation, please add it.


Ok.

I need 1 more clarification. There is a file core.cxx which is not part
of/class
in itself. Should I alter this file and call it say Utils class ? Since this
method
is used within the asycxx code, i'll create the class structure in the .cxx
file
itself.

-- 
Karthik

HiPro IT Solutions Pvt. Ltd.
http://hipro.co.in/

Re: [asycxx-devel] Documentation changes query

[Joe S. <js...@hi...>]

On Tue, 2009-03-17 at 12:06 +0530, Karthik Balakrishnan wrote:

> Alright. I got few files fixed as noted. But I wasn't sure if i was on
> the right track. I'll send you the patch file tonight/later this
> evening.

Alright. In fact it makes sense to move 'api documentation' to the .h
files. All public and protected methods need to come in the api docs.
The private methods can be simply documented (without doxygen tags) for
our own reference.

> I need 1 more clarification. There is a file core.cxx which is not
> part of/class in itself. Should I alter this file and call it say
> Utils class ? 

That file simply contains some common functions used everywhere. It
makes sense to put them as static functions in a 'Utils' class, coz we
dont want to associate them to an object. But, well. It is totally
internal to us, so I dont care.

> Since this method is used within the asycxx code, i'll create the
> class structure in the .cxx file itself.

I did not understand this. 

-- 
Joe Steeve
HiPro IT Solutions Pvt. Ltd.
http://hipro.co.in/

Re: [asycxx-devel] Documentation changes query

[Karthik B. <ka...@hi...>]

2009/3/17 Joe Steeve <js...@hi...>

> Alright. In fact it makes sense to move 'api documentation' to the .h
> files. All public and protected methods need to come in the api docs.
> The private methods can be simply documented (without doxygen tags) for
> our own reference.


Taken.


> That file simply contains some common functions used everywhere. It
> makes sense to put them as static functions in a 'Utils' class, coz we
> dont want to associate them to an object. But, well. It is totally
> internal to us, so I dont care.


Fine. If possible, i'll check if I can get it done (later obviously)


> > Since this method is used within the asycxx code, i'll create the
> > class structure in the .cxx file itself.
>
> I did not understand this.


It was about the core.cxx file itself. Ignore it. I got what is needed.

-- 
Karthik

HiPro IT Solutions Pvt. Ltd.
http://hipro.co.in/

Re: [asycxx-devel] Documentation changes query

[Joe S. <js...@hi...>]

On Tue, 2009-03-17 at 12:46 +0530, Karthik Balakrishnan wrote:

>         That file simply contains some common functions used
>         everywhere. It makes sense to put them as static functions in
>         a 'Utils' class, coz we dont want to associate them to an
>         object. But, well. It is totally internal to us, so I dont
>         care.
> 
> Fine. If possible, i'll check if I can get it done (later obviously)

Yeah. It is not important now.

-- 
Joe Steeve
HiPro IT Solutions Pvt. Ltd.
http://hipro.co.in/