[SrcML] ChangeLog and Javadocs

[Frank R. <fra...@in...>]

I have created a ChangeLog [1] page on the wiki to better document the
development process after the 0.2 release. If you make any changes to the
codebase please add a short entry to the ChangeLog list.
This serves as a remainder just as well as allowing others to stay informed
about the current changes. The list is split up into major and minor changes,
whereas the major changes should be those which will be mentioned in the next
release message.

I also added support for javadoc tags to the API. A few changes had to be made
to how javadoc comments are treated [2] and printed through the
PrintSelectionPlugin. The javadoc support does not care about the tags
actually defined by the javadoc specification. Any tag name could be used.
Therefore we also don't know if a tag is parameterized (like f.ex.
@param <param name> <description>) and we treat all tags equal as
@tag <description>. If you want to work with @param you would have to manually
cut off the first word from the description to get the actual parameter name.
I'm not sure if we should integrate support for that into the API, as we would
have to support tags with a multiple number of parameters too then.
In order to not destroy significant whitespace within comments the description
might contain actual \n characters to mark linebreaks.
Here's a sample javadoc comment and what the API is seeing:

/**
 **Some text
 * * split into two lines.
 * @param f_param parameter description
 * @return
 something is returned
 */

Javadoc.getComment() will return "Some text * split into two lines."
Javadoc.getTags() will return a List<Javadoc.Tag> with the first tag
being the param tag with tag.getName() returning "param" and 
tag.getDescription() returning "f_param parameter description". The
second tag will have the name "return" and the description will
reflect the newline: "\nsomething is returned".

When printed through the ViewPlatform again the comment should look like
this:

/**
 * Some text * split into two lines.
 *
 * @param f_param parameter description
 * @return
 * something is returned
 */


[1] http://www.uni-ulm.de/~s_fraise/cgi-bin/moin.cgi/ChangeLog

[2] I'm aware that it's impossible to interpret comments correctly, but I hope
that the current implementation destroys as few significant parts of the
comment as possible, while still creating a decent output.

-- 
Raiser, Frank
Student @ University of Ulm (www.uni-ulm.de)

Poor management can increase software costs more rapidly
than any other factor. (Barry Boehm)