Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdesdk@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 170 insertions, 0 deletions

diff --git a/doc/umbrello/code_import_and_generation.docbook b/doc/umbrello/code_import_and_generation.docbook
new file mode 100644
index 00000000..8beffcc3
--- /dev/null
+++ b/doc/umbrello/code_import_and_generation.docbook
@@ -0,0 +1,170 @@
+<chapter id="code-import-generation">
+<title>Code Import and Code Generation</title>
+<para>
+&umbrello; is a &UML; modelling tool, and as such its main purpose is to help you in the 
+<emphasis>analysis and design</emphasis> of your systems. However, to make the transition
+between your design and your <emphasis>implementation</emphasis>, &umbrello; allows you to
+generate source code in different programming languages to get you started. Also, if you 
+want to start using &UML; in an already started C++ project, &umbrello; can help you create a model
+of your system from the source code by analysing your source code and importing the classes
+found in it.
+</para>
+<sect1 id="code-generation">
+<title>Code Generation</title>
+<para>
+&umbrello; can generate source code for various programming languages based on your &UML; Model
+to help you get started with the implementation of your project. The code generated consists
+of the class declarations, with their methods and attributes so you can <quote>fill in the
+blanks</quote> by providing the functionality of your classes' operations.
+</para>
+<para>
+&umbrello; 1.2 comes with code generation support for ActionScript, Ada, C++, CORBA IDL, &Java;, JavaScript, <acronym>PHP</acronym>, Perl, Python, SQL and XMLSchema. 
+</para>
+<sect2 id="generate-code">
+<title>Generating Code</title>
+<para>
+In order to generate code with &umbrello;, you first need to create or load a Model
+containing at least one class. When you are ready to start writing some code, select the
+<guimenuitem>Code Generation Wizard</guimenuitem> entry from the <guimenuitem>Code</guimenuitem> menu to 
+start a wizard which will guide you trough the code generation process.
+</para>
+<para>
+The first step is to select the classes for which you want to generate source code.
+By default all the classes of your model are selected, and you can remove the ones
+for which you do not want to generate code by moving them to the left-hand side list.
+</para>
+<para>
+The next step of the wizard allows you to modify the parameters the Code Generator uses
+while writing your code. The following options are available:
+</para>
+<para>
+<screenshot>
+<screeninfo>Code Generation Options</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="generation-options.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Options for the Code Generation in &umbrello;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Options for the Code Generation in &umbrello;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+<sect3 id="generation-options">
+<title>Generation Options</title>
+<!-- LW; to rearrange -->
+
+<sect4>
+<title>Code Verbosity</title>
+<para>
+The option <guilabel>Write documentation comments even if empty</guilabel> instructs the
+ Code Generator to write comments of the /** blah */ style even if the comment blocks are empty.
+If you added documentation to your classes, methods or attributes in your Model, the
+Code Generator will write these comments as <application>Doxygen</application> documentation regardless of what you set here, but
+if you select this option &umbrello; will write comment blocks for all classes, methods and attributes
+even if there is no documentation in the Model, in which case you should document your classes
+later directly in the source code.
+</para>
+<para>
+<guilabel>Write comments for sections even if section is empty</guilabel> causes &umbrello; to write comments
+in the source code to delimit the different sections of a class. For example <quote>public methods</quote>
+ or <quote>Attributes</quote> before the corresponding sections. If you select this option &umbrello; 
+ will write comments for all sections of the class even if the section is empty. For example,
+ it would write a comment saying <quote>protected methods</quote> even if there are no protected 
+ methods in your class.
+</para>
+</sect4>
+<sect4>
+<title>Folders</title>
+<para>
+<guilabel>Write all generated files to folder</guilabel>. Here you should select the folder 
+where you want &umbrello; to put the generated sources.
+</para>
+<para>
+The <guilabel>Include heading files from folder</guilabel> option allows you to insert a 
+heading at the beginning of each generated file. Heading files can contain copyright or licensing
+ information and contain variables that are evaluated at generation time. You can take a look
+ at the template heading files shipped with &umbrello; to see how to use this variables for replacing
+ your name or the current date at generation time.
+</para>
+</sect4>
+<sect4>
+<title>Overwrite Policy</title>
+<!-- FIXME update for Umbrello 1.2's new C++ and Java code generators -->
+<para>
+This option tells &umbrello; what to do if the file it wants to create already exists in
+the destination folder. &umbrello; <emphasis>cannot modify existing source files</emphasis>,
+so you have to choose between overwriting the existing file, skipping the generation of
+that particular file or letting &umbrello; choose a different file name. If you choose the option
+to use a different name, &umbrello; will add a suffix to the file name.
+</para>
+</sect4>
+<sect4>
+<title>Language</title>
+<para>
+&umbrello; will by default generate code in the language you have selected as Active Language, but
+with the Code Generation Wizard you have the option to change this to another language.
+</para>
+</sect4>
+</sect3><!--generation-options-->
+<sect3 id="generation-wizard-generation">
+<title>Generation Wizard Generation</title>
+<para>
+The third and last step of the wizard shows the status of the Code Generation process.
+You need only to click on the Generate button to get your classes written for you.
+</para>
+<para>
+Note that the Options you select during the Code Generation Wizard are only valid for the current
+generation. The next time you run the wizard you will need to re-select all the options
+(your headings folder, overwrite policy, and so on). You can set the defaults used by &umbrello; 
+in the <guilabel>Code Generation</guilabel> section of the &umbrello; settings, available
+at <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &umbrello;...</guimenuitem></menuchoice>
+</para>
+<para>
+If you have set your Code Generation options to the right settings and want to generate
+some code right away without going through the wizard, you can select the entire 
+<guimenuitem>Generate All Code</guimenuitem> from the Code menu. 
+This will generate code for all the classes in your Model using the current settings 
+(including Output Folder and Overwrite Policy, so use with care).
+</para>
+</sect3>
+</sect2><!--generate-code-->
+</sect1> <!--code-generation-->
+<sect1 id="code-import">
+<title>Code Import</title>
+<para>
+&umbrello; can import source code from your existing projects to help you build Model of 
+your systems. &umbrello; 1.2 supports only C++ source code, but other languages
+should be available in future versions.
+</para>
+<para>
+To import classes into your Model, select the entry <guimenuitem>Import Classes...</guimenuitem> from
+the <guimenu>Code</guimenu> menu. In the file dialog select the files containing the C++
+class declarations and press OK. The classes will be imported and you will find them as part of
+your Model in the Tree View. Note that &umbrello; will not create any kind of Diagram for showing
+your classes, they will only be imported into your Model so that you can use them later in any 
+diagram you want.
+</para>
+<para>
+<screenshot>
+<screeninfo>Code Import</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="code-import.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Menu for importing source code in &umbrello;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Menu for importing source code in &umbrello;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+</sect1>
+</chapter> <!--code-import-generation-->