Planet SoC

Ahhhh, I feel too tired to clearly articulate myself right now. I think I’m going to have to finish this tomorrow morning. I need to stop working/blogging so late- I’m really much more in my element in the morning… Like Cinderella’s coach, my brain turns into a pumpkin past midnight- which makes my time commitment from 7-11pm M T TH a little inconvenient ><
Plan details
Stage 1:

Picking up comments
in cscanner.c at case SWIG_TOKEN_COMMENT:
(around line 420 in my version)
3 types of tokens will be returned
-for standard doxygen blobs (aka /** or ///, //! etc) DOXYGENSTRING

-for post comments suchas /**< ///< etc (which are associated with the last thing encountered, see “Putting comments after members” at http://www.stack.nl/~dimitri/doxygen/docblocks.html for more info) DOXYGENPOSTCOMMENT

-for normal C/C++ comments CSTYLECOMMENT

Stage 2:
Attachment into the parse tree
in parser.y

General Doxygen Comments:
there are a few difficulties here- one being that occasionally comments exist independent of the location of the object they describe- they contain structural indicators:

\struct to document a C-struct.
\union to document a union.
\enum to document an enumeration type.
\fn to document a function.
\var to document a variable or typedef or enum value.
\def to document a #define.
\typedef to document a type definition.
\file to document a file.
\namespace to document a namespace.
\package to document a Java package.
\interface to document an IDL interface.

The best possible way, in my opinion, to deal with these is to make them their own nodes. It seems like it is standard to put any structural commands as the first command in a blob- so :
incoming doxygen strings are scanned until the first command is encountered, then the command is tested to see if it belongs to this small list. If it does belong, a new NODE is created with only an attribute named something like structuralDoxygenComment, containing the Doxygen Blob. (is making new node okay to do?)

Otherwise it is handled per usual- currentDoxygenComment would be set to the comment, and when a new node is formed the Doxygen Comment is attached as an attribute.

Post Comments would be added to the previous node by appending them to whatever existing (or not existing) doxygen comment entity may be an attribute in the node. The previous node would be kept track of by a global pointer.

C/C++ Comments are tricky.. because there are two ways that are common to comment:
//Function foo
int foo();

or int foo(); //the function foo
I’m not sure how to distinguish between the two >.< It doesn’t seem like it would be efficient to make every little C/C++ comment its own node, but I’m also not sure how to get it to associate C/C++ comments with the proper object given the ambiguity of C/C++ comments.

In general, by that point all “Traditional” and post-comments that are describing the same element should be in the same “blob” passed to my module- so they would be processed “together” by my blob-translating module.
My thoughts on SWIG directives are now too fuzzy to explain before I’ve slept >< Reguardless, the end result should be that my separate module doesn’t have to do anything more than translate what its given- and thus the language modules should only need to pass the blobs to translate where appropriate. The less I have to fiddle with the individual language modules, the better, I believe

Rest of this will be tomorrow! Manyana Manyana Manyana.
Extra thanks to Olly for informing me all of my post titles were based around the wrong month :-) Oops…