It Begins!
Hopefully writing down my progress will hold me well to my path :)
My name is Cheryl Foil- I am currently a student at the College of William and Mary.
My project for SWIG is taking C/C++/Doxygen comments from C/C++ files and placing them into the class that the other language works with- in the appropriate documentation language.
IE- If I am working with an example.c, the generated example.java will have the comments of example.c in JavaDoc :)
The first few steps have been very intimidating- After setting everything up and checking I could compile/run it- I have been combing through the SWIG manuals/Developers resources as well as pawing through the SWIG code itself.
As it stands, I am most comfortable with Java and JavaDoc- and my end goal is JavaDoc and PythonDoc implemented. For the time being, my concentration will be with Java- and I plan to write most of my test cases/sample in Java for that reason. It’s pretty apparent I should revise my milestones- no reason to extrapolate to the very end for now :) :
Start: May 26th
clarification- when i say file.c, I mean the c/c++ code- and when i say file.java, I mean the file where the comments should be appearing.
Milestone 1:
-PROOF OF CONCEPT-
Write a few trivial samples (will just be building off of the SWIG examples with some comments)
Play with the parser: write some parsing rules so large “blobs” of comments are parsed- IE
/*This Function is returns the GCD of x and y*/
Get the comments to appear verbatim in file.java—- *in the right place*
Milestone 2:
After the “hands on work” in MS 1- a step back to planning correctly
Concentrate on the usual cases- proper use of Doxygen comments, C/C++ comments. Decide what I do and do not want to cover. Become familiar enough with parsing rules to know what is and isn’t feasible, how to deal with sloppy cases, etc.
Write sample cases for all of this - including cases I don’t know how to deal with.
Decide what to do about circumstances like int x; // variable description
Research common entities in documentation language- such as @author, etc. Plan for these universal types, figure out a way to handle the other stuff.
Milestone 3:
Predominantly parsing rules.
Get all of the entities to appear in the parse tree correctly.
Design a coping strategy for rogue comments.
Milestone 4:
Get all of the entities to appear in the right place in file.java
Milestone 5:
Work on producing a JavaDoc module
and so on.