[plug] parsing C++ code/comments

[Buddrige, David]

Hi all,

We have a  bunch of C++ code that has been commented using DOC++.  By this I
mean that in the class definition, there is a DOC++ comment containing a
short description of each method directly above each method declaration.
Similarly, in the implementation file, for each method definition, there is
a DOC++ comment directly above it describing the method in detail.  For
example given a class .C and .H file we might have this in the .H file

/**
	@doc This is myClass that does something or other.
*/
class myClass
{
public:
	/// @memo This is function 1 brief description.
	int function1(void);
	/// @memo This is function2 brief description.
	int function2(int i);
protected:
	/// @memo This is the protected_method brief description.
	char *protected_method(void);
private:
	/// @memo This is the private_method brief description.
	int private_method(void);
};


And in the .C file we have something like this:



/**
@doc Detailed info about function 1
@precondition Precondition for this function
@postcondition Postcondition for this function
@invariant Invariant for this function
*/

int myClass::function1(void)
{
}

/**
@doc Detailed info about function 2
@precondition Precondition for this function
@postcondition Postcondition for this function
@invariant Invariant for this function
*/


int myClass::function2(int i)
{
}

/**
@doc Detailed info about protected_method
@precondition Precondition for this function
@postcondition Postcondition for this function
@invariant Invariant for this function
*/

char *myClass::protected_method(void)
{
}

/**
@doc Detailed info about private_method
@precondition Precondition for this function
@postcondition Postcondition for this function
@invariant Invariant for this function
*/

int myClass::private_method(void)
{
}




OK.  I've been instructed that the client only actually wants the public
methods documented - NOT the private and protected methods, and so what I
want to do is to find some way of automatically removing from the code the
doc++ comments for protected and private methods, so that only comments for
the public methods remain.

This is reasonably trivial to do in the .H file since you just look for the
keyword "protected" or "private" and scrub any comments you find between
them and the end of that declaration section or the end of the class.

However to do it in the .C file is a bit more complicated.  At this point,
the only way I can see of doing it (reliably) would be to write a moderately
detailed parser for the C++ code which cross-references the function
declaration in the class definition and the function implementation and then
removes the first doc++ comment it comes across *directly prior* to the
function concerned when the function falls in the protected or private
scope.

This problem has "perl" written all over it - I know - the only problem is
that I don't know Perl.  I DO know C++/STL reasonably well, but am trying to
see if there is a way to do this that is faster than writing a parser.

Does anyone have any suggestions on an alternative approach to this problem?

thanks heaps

David Buddrige.

This e-mail and any attachment is for authorised use by the intended recipient(s) only.  It may contain proprietary material, confidential information and/or be subject to legal privilege.  It should not be copied, disclosed to, retained or used by, any other party.  If you are not an intended recipient then please promptly delete this e-mail and any attachment and all copies and inform the sender.  Thank you.