diff options
Diffstat (limited to 'doc/umbrello/code_import_and_generation.docbook')
| -rw-r--r-- | doc/umbrello/code_import_and_generation.docbook | 170 |
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--> |