<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-15">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Hi, <br>
<br>
in the last days I took time to unify some stuff between the
soc-umbrello branch and trunk, for getting a better overview of what
is changed and what is required to merge usefull changes from the
soc-umbrello branch into trunk (trunk is still the master branch and
development branches should be merged into ?). <br>
<br>
Yesterday I started to review the differences in the widget classes
and recognized, that the soc-umbrello uses a document-in-cpp-file
approach as documented in trunks coding style document, while trunk
uses a sometime-document-in-header,
sometime-document-in-header-and-cpp-file and
sometime-document-in-cpp-file <br>
approach, which makes it hard to compare. <br>
<br>
I started to restruct some smaller classes to the document-in-cpp
style (see svn log) and saw, that such work may be done with
umbrello. Umbrello is able to import classes and to generate code,
so it should be able to let umbrello do the job. <br>
<br>
So I imported activitywidget.h and activitywidget.cpp (the cpp file
is important because it contains the method comments) and generated
code from the import. <br>
Because the original code is present it is easy to compare the
results, which are here:<br>
<br>
1. The header copyright comment is merged with the class comment <br>
2. included headers, forward declarations and other declarations
are not added to the generated header file <br>
3. The class ActivityWidget is derived two times from UMLWidget (may
be from the cpp import ?)<br>
4. method bodies are not imported <br>
5. mostly methods are defined as inline methods in the generated
header <br>
6. umbrello adds an empty constructor - implemented in the cpp files
<br>
7. umbrello adds a method initAttributes, called from the
constructor <br>
8. Although I choosed /** */ comment form there are // comments
inside the files <br>
9. The generator uses camel-cased filenames - umbrello uses lower
case filenames <br>
10. The generator adds additional comments about scopes <br>
11. The generator documents methods in the header<br>
<br>
Things to inspect: <br>
12. It is unclear what happens when a method is documented in the
header *and* the cpp<br>
<br>
I thought about how to solve the issues. Here is my brain dump: <br>
<br>
1. The header copyright comment is merged with the class comment <br>
-> There may be more than one class in a file - it make
sense to create - for each imported file - a file artifact (with
folders) in the component view and to add a kind of association
between the class and the artifact, so that the generator is able
to map classes to filenames <br>
<br>
2. included headers are not added to the generated header file <br>
-> The easiest way is to add all definitions into the related
file artifact (see 1.). The generator should check if an
constructed include is already defined here to avoid double
includes. <br>
<br>
3. The class ActivityWidget is derived two times from UMLWidget<br>
a bug ? <br>
<br>
4. method bodies are not imported <br>
a bug ? <br>
<br>
5. mostly methods are defined as inline methods in the generated
header <br>
-> the importer should note an "inline" flag for class
methods <br>
<br>
6. umbrello adds an empty constructor - implemented in the cpp files
<br>
-> generator option <br>
<br>
7. umbrello adds a method initAttributes, called from the
constructor <br>
-> generator option <br>
<br>
8. Although I choosed /** */ comment form there are // comments
inside the files <br>
-> generator fix<br>
<br>
9. The generator uses camel-cased filenames - umbrello uses lower
case filenames <br>
-> generator option, take name from file artifact generated
in 1.<br>
<br>
10. The generator adds additional comments about scopes <br>
-> should be disabled by a generator option <br>
<br>
11. The generator documents methods in the header<br>
-> should be switchable by generator options for class,
method, members, type and other documentation. <br>
doxygen allows to document code on any place<br>
<font face="Verdana, Arial, Helvetica" size="-1">
<pre class="fragment">/** @class Test
* @brief Test class.
*
* Details about Test.
*/
/** @fn const char *Test::member(char c,int n)
* @brief A member function.
* @param c a character.
* @param n an integer.
* @exception std::out_of_range parameter is out of range.
* @return a character pointer.
*/
BTW: supporting documenation at other places as the definition needs an importer parse patch
</pre>
</font>12. It is unclear what happens when a method is documented in
the header *and* the cpp<br>
-> comment should be merged (remove identical comments)<br>
<br>
<br>
BTW: I hink having such a documentation-cleanup feature in umbrello
would give umbrello a uniq feature and could be used for marketing.
<br>
<br>
Regards<br>
Ralf <br>
</body>
</html>