[Uml-devel] umbrello use case

[Ralf Habacker]

Hi,

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 ?).

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
approach, which makes it hard to compare.

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.

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.
Because the original code is present it is easy to compare the results, 
which are here:

1. The header copyright comment is merged with the class comment
2. included headers, forward declarations and other declarations  are 
not added to the generated header file
3. The class ActivityWidget is derived two times from UMLWidget (may be 
from the cpp import ?)
4. method bodies are not imported
5. mostly methods are defined as inline methods in the generated header
6. umbrello adds an empty constructor - implemented in the cpp files
7. umbrello adds a method initAttributes, called from the constructor
8. Although I choosed /** */ comment form there are // comments inside 
the files
9. The generator uses camel-cased filenames - umbrello uses lower case 
filenames
10. The generator adds additional comments about scopes
11. The generator documents methods in the header

Things to inspect:
12. It is unclear what happens when a method is documented in the header 
*and* the cpp

I thought about how to solve the issues. Here is my brain dump:

1. The header copyright comment is merged with the class comment
     ->  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

2. included headers are not added to the generated header file
     -> 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.

3. The class ActivityWidget is derived two times from UMLWidget
      a bug ?

4. method bodies are not imported
      a bug ?

5. mostly methods are defined as inline methods in the generated header
      -> the importer should note an "inline" flag for class methods

6. umbrello adds an empty constructor - implemented in the cpp files
      -> generator option

7. umbrello adds a method initAttributes, called from the constructor
      -> generator option

8. Although I choosed /** */ comment form there are // comments inside 
the files
     -> generator fix

9. The generator uses camel-cased filenames - umbrello uses lower case 
filenames
      -> generator option, take name from file artifact generated in 1.

10. The generator adds additional comments about scopes
      -> should be disabled by a generator option

11. The generator documents methods in the header
      -> should be switchable by generator options for class, method, 
members, type and other documentation.
      doxygen allows to document code on any place

/** @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

12. It is unclear what happens when a method is documented in the header 
*and* the cpp
     -> comment should be merged (remove identical comments)


BTW: I hink having such a documentation-cleanup feature in umbrello 
would give umbrello a uniq feature and could be used for marketing.

Regards
  Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/umbrello-devel/attachments/20111214/fdbdb18b/attachment.html>