Thread: [asycxx-devel] Documentation changes query
Status: Alpha
Brought to you by:
joe_steeve
Menu
▾
▴
asycxx-devel
|
From: Karthik B. <ka...@hi...> - 2009-03-16 18:53:18
|
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/ |
|
From: Joe S. <js...@hi...> - 2009-03-17 06:01:54
|
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/ |
|
From: Karthik B. <ka...@hi...> - 2009-03-17 06:36:48
|
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/ |
|
From: Joe S. <js...@hi...> - 2009-03-17 06:59:02
|
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/ |
|
From: Karthik B. <ka...@hi...> - 2009-03-17 07:16:26
|
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/ |
|
From: Joe S. <js...@hi...> - 2009-03-17 09:11:36
|
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/ |
Thanks for helping keep SourceForge clean.
X