Menu
Logged-In As
ACCOUNTNot Logged In
Doxygen cleanup ... for LIBBNBRL-CAD
Status: ClosedTime to complete:
48 hrs
Mentors: Sean
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output. This task involves cleaning up the Doxygen comments in the library so that useful reports and API documentation automatically generated (correctly, completely, and cleanly). Verify/fix any Doxygen syntax. Verify/fix groups so that functions are organized neatly and all contained within a group. Provide patches that give clean (PDF) output from Doxygen. References:
There are approximately 300 documented API function calls in LIBBN. Code:
|
Uploaded Work
| File name/URL | File size | Date submitted | |
|---|---|---|---|
| doxygen_cleanup.patch | 14.2 KB | December 08 2012 21:29 UTC | |
| doxygen_output.zip | 15.4 MB | December 10 2012 09:09 UTC | |
| libbn_doxygen_output.zip | 2.3 MB | December 11 2012 19:17 UTC | |
| xxx.patch | 12.0 KB | December 13 2012 19:50 UTC | |
| doxygen_output.zip | 16.0 MB | December 14 2012 21:43 UTC |
I would like to work on this task.
This task has been assigned to Mrowqa. You have 48 hours to complete this task, good luck!
The work on this task is ready to be reviewed.
Mrowqa, since this task involves verifying/fixing the output, would you post the output from Doxygen? Ideally a pdf, but tarball of the html pages works fine too.
At a glance, the patch looks good if that was all that was needed.
Did you run into any problems?
The deadline of the task has been extended with 1 days and 0 hours.
I don't know what you mean 'doxygen output', so I uploaded generated documentation and output from console by:
brlcad@brlcad-vm:~/brlcad-svn$ doxygen misc/Doxyfile 2 doxygen.output
Stdout is clear, all output from console is in stderr.
Melange has detected that the deadline has passed and no more work can be submitted. The submitted work should be reviewed.
Mrowqa, the Doxyfile that we provide scans the ENTIRE project. If you review that html directory and go to main.html and select modules, you'll see it's everything. This task is only to review and generate output for LIBBN. Basically, that's the task -- make a Doxyfile for just LIBBN and make sure the output (the html directory) makes sense by putting comments into groups.
Also, what you submitted is what we were looking for. Output from doxygen and the resulting generated html. Pay particular attention to the warnings when you limit the scan to just the libbn files. You'll not want to let it scan everything in the include directory, just headers belonging to libbn, which are bn.h, dvec.h, vmath.h, plot3.h, and vector_*.h at a glance (you should confirm). You may need to also include common.h, bio.h, bin.h if doxygen complains.
One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.
The deadline of the task has been extended with 2 days and 0 hours.
The work on this task is ready to be reviewed.
Mrowqa, that output looks better but it doesn't look like you did any cleanup? Note how multipoly isn't included in the libbn group. The 'Fort' group is odd, but that's deprecated code so we can ignore it.
Looking through the list, animation looks great but axis is empty. When I get to complex numbers, it becomes clear that you're also scanning old source code. You should be scanning our latest subversion sources. See http://brlcad.org/wiki/Deuces for help getting started and please do ask questions if you have any.
One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.
The deadline of the task has been extended with 1 days and 0 hours.
The work on this task is ready to be reviewed.
Ehh... Melange didn't add my last comment... :/
I did exactly as you wrote on IRC - I moved Multipoly to Libbn group and added axis.c to Axis group. You can call me "Artur Jamro (Mrowqa)" as patch author.
Melange has detected that the deadline has passed and no more work can be submitted. The submitted work should be reviewed.
The deadline of the task has been extended with 1 days and 0 hours.
Arturo, the patch looks good, but also waiting for the updated output from Doxygen (the html files). Thanks for your efforts!
One of the mentors has sent this task back for more work. Talk to the mentor(s) assigned to this task to satisfy the requirements needed to complete this task, submit your work again and mark the task as complete once you re-submit your work.
The work on this task is ready to be reviewed.
Congratulations, this task has been completed successfully.
Arturo, you may want to try an easier task next time as there were still significant problems. You once again submitted a scan of the entire source repository, not just libbn. There were also several obvious errors in the libbn section. Still, I'm marking this task as completed in order to recognize the effort you've put in on the comment patch. We'll likely need to repost the task though as there is additional cleanup still needed, but thank you for your efforts.
As GCI comes to a close, we wanted to take the time to say THANK YOU for all your efforts. This comment interface closes after GCI is over, so you're encouraged to join our mailing list where we'll be announcing contributions from GCI participants like yourelf over the upcoming months:
https://lists.sourceforge.net/lists/listinfo/brlcad-news
If you've provided your full name, we'll be sure to credit you in our authorship documentation and you'll see your name in a future announcement. If you contact us at devs@brlcad.org or via IRC, we'll even let you know when your work is integrated and follow up with updates. You're welcome and encouraged to contact us any time, especially if you have a question about how to continue participating in Open Source after GCI is over, but even if just to keep in touch. Note that ongoing participation in Open Source is one of the most impressive skills to have on your resumé. Take care, be well, and thank you again!