Updated docs

gossi · gossi · commit 0adb2cec45c0 · 2016-11-15T18:13:15.000+01:00
diff --git a/docs/best-practices.rst b/docs/best-practices.rst
@@ -11,8 +11,27 @@ It is useful to use some kind of template system to load the contents for your b
 Hack in Traits
 --------------
 
-Let's assume you generate a php class. This class will be used in your desired framework as it serves a specific purpose in there. It possible needs to fulfill an interface or some abstract methods and your generated code will also take care of this - wonderful. Now imagine the programmer wants to change the code your code generation tools created. Once you run the tools again his changes probably got overwritten, which would be bad.
-Here is the trick: First we declare the generated class as "host" class. Your code generation tools should first check if the host class exists and if not create it, or if it exists, load the existing class. For the possible required methods your host class must contain create a trait and implement the required logic at the trait. Check in the host class, if the trait is available and add it if not present. Now you only need to write the host class if there is an update (or if your code generation tools have some kind of force parameter). It also keeps programmer modified code intact and your tools can safely overwrite the trait. If you want to give the programmer more freedom offer him hook methods in the host class, that - if he wants to - can overwrite with his own logic.
+Let's assume you generate a php class. This class will be used in your desired framework as it serves a specific purpose in there. It possible needs to fulfill an interface or some abstract methods and your generated code will also take care of this - wonderful. Now imagine the programmer wants to change the code your code generation tools created. Once you run the code generation tools again his changes probably got overwritten, which would be bad.
+
+Here is the trick: First we declare the generated class as "host" class:
+
+.. image:: images/hack-in-trait.png
+	:width: 50%
+	:align: center
+
+Your generated code will target the trait, where you can savely overwrite code. However, you must make sure the trait will be used from the host class and also generate the host class, if it doesn't exist. So here are the steps following this paradigm:
+
+
+1. Create the trait
+2. Check if the host class exists
+
+   a. if it exists, load it
+   b. if not, create it
+
+3. Add the trait to the host class
+4. Generate the host class code
+
+That way, the host class will be user-land code and the developer can write his own code there. The code generation tools will keep that code intact, so it won't be destroyed when code generation tools run again. If you want to give the programmer more freedom offer him hook methods in the host class, that - if he wants to - can overwrite with his own logic.
 
 Format in Post-Processing
 -------------------------
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+#version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0'
+#release = '1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -112,6 +112,8 @@
 # a list of builtin themes.
 html_theme = 'sphinx_rtd_theme'
 
+html_style = 'style.css'
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -139,7 +141,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-#html_static_path = ['_static']
+html_static_path = ['static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/docs/generator.rst b/docs/generator.rst
@@ -26,20 +26,39 @@ Generates code for a given model. Additionally (and by default), it will generat
 * Config: ``gossi\codegen\config\CodeGeneratorConfig``
 * Options:
 
-  +-------------------------+---------+---------------+-----------------------------------------------------------------------------+
-  | Key                     | Type    | Default Value | Description                                                                 |
-  +=========================+=========+===============+=============================================================================+
-  | generateDocblock        | boolean | true          | enables docblock generation prior to code generation                        |
-  +-------------------------+---------+---------------+-----------------------------------------------------------------------------+
-  | generateEmptyDocblock   | boolean | true          | allows generation of empty docblocks                                        |
-  +-------------------------+---------+---------------+-----------------------------------------------------------------------------+
-  | generateScalarTypeHints | boolean | false         | generates scalar type hints, e.g. in method/function parameters (PHP 7)     |
-  +-------------------------+---------+---------------+-----------------------------------------------------------------------------+
-  | generateReturnTypeHints | boolean | false         | generates scalar type hints for return values (PHP 7)                       |
-  +-------------------------+---------+---------------+-----------------------------------------------------------------------------+
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | Key                     | Type                              | Default Value | Description                                                             |
+  +=========================+===================================+===============+=========================================================================+
+  | generateDocblock        | boolean                           | true          | enables docblock generation prior to code generation                    |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | generateEmptyDocblock   | boolean                           | true          | allows generation of empty docblocks                                    |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | generateScalarTypeHints | boolean                           | false         | generates scalar type hints, e.g. in method/function parameters (PHP 7) |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | generateReturnTypeHints | boolean                           | false         | generates scalar type hints for return values (PHP 7)                   |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | enableSorting           | boolean                           | true          | Enables sorting                                                         |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | useStatementSorting     | boolean|string|Closure|Comparator | default       | Sorting mechanism for use statements                                    |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | constantSorting         | boolean|string|Closure|Comparator | default       | Sorting mechanism for constants                                         |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | propertySorting         | boolean|string|Closure|Comparator | default       | Sorting mechanism for properties                                        |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
+  | methodSorting           | boolean|string|Closure|Comparator | default       | Sorting mechanism for methods                                           |
+  +-------------------------+-----------------------------------+---------------+-------------------------------------------------------------------------+
 
   **Note**: when ``generateDocblock`` is set to ``false`` then ``generateEmptyDocblock`` is ``false`` as well.
 
+  **Note 2**: For sorting ...
+
+  * ... a string will used to find a comparator with that name (at the moment there is only default).
+  * ... with a boolean you can disable sorting for a particular member
+  * ... you can pass in your own ``\Closure`` for comparison
+  * ... you can pass in a Comparator_ for comparison
+
+.. _Comparator: https://phootwork.github.io/lang/comparison/
+
 * Example:
 
   ::
@@ -63,17 +82,17 @@ Generates a complete php file with the given model inside. Especially useful whe
 * Config: ``gossi\codegen\config\CodeFileGeneratorConfig``
 * Options: Same options as ``CodeGenerator`` plus:
 
-  +--------------------+-----------------+---------------+----------------------------------------------------------------------------------------+
-  | Key                | Type            | Default Value | Description                                                                            |
-  +====================+=================+===============+========================================================================================+
-  | headerComment      | string          | empty         | A comment, that will be put after the ``<?php`` statement                              |
-  +--------------------+-----------------+---------------+----------------------------------------------------------------------------------------+
-  | headerDocblock     | string|Docblock | empty         | A docblock that will be positioned after the possible header comment                   |
-  +--------------------+-----------------+---------------+----------------------------------------------------------------------------------------+
-  | blankLineAtEnd     | boolean         | true          | Places an empty line at the end of the generated file                                  |
-  +--------------------+-----------------+---------------+----------------------------------------------------------------------------------------+
-  | declareStrictTypes | boolean         | false         | Whether or not a ``declare(strict_types=1);`` is placed at the top of the file (PHP 7) |
-  +--------------------+-----------------+---------------+----------------------------------------------------------------------------------------+
+  +--------------------+----------------------+---------------+----------------------------------------------------------------------------------------+
+  | Key                | Type                 | Default Value | Description                                                                            |
+  +====================+======================+===============+========================================================================================+
+  | headerComment      | null|string|Docblock | null          | A comment, that will be put after the ``<?php`` statement                              |
+  +--------------------+----------------------+---------------+----------------------------------------------------------------------------------------+
+  | headerDocblock     | null|string|Docblock | null          | A docblock that will be positioned after the possible header comment                   |
+  +--------------------+----------------------+---------------+----------------------------------------------------------------------------------------+
+  | blankLineAtEnd     | boolean              | true          | Places an empty line at the end of the generated file                                  |
+  +--------------------+----------------------+---------------+----------------------------------------------------------------------------------------+
+  | declareStrictTypes | boolean              | false         | Whether or not a ``declare(strict_types=1);`` is placed at the top of the file (PHP 7) |
+  +--------------------+----------------------+---------------+----------------------------------------------------------------------------------------+
 
   **Note**: ``declareStrictTypes`` sets ``generateScalarTypeHints`` and ``generateReturnTypeHints`` to ``true``.
 
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -80,7 +80,8 @@ c) From Reflection:
 	use gossi\codegen\generator\CodeGenerator;
 	use gossi\codegen\model\PhpClass;
 
-	$class = PhpClass::fromReflection(new \ReflectionClass('MyClass'));
+    $reflection = new \ReflectionClass('MyClass');
+	$class = PhpClass::fromReflection($reflection->getFileName());
 
 	$generator = new CodeGenerator();
 	$code = $generator->generate($class);
diff --git a/docs/images/hack-in-trait.odg b/docs/images/hack-in-trait.odg
diff --git a/docs/images/hack-in-trait.png b/docs/images/hack-in-trait.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,42 @@
 Welcome to PHP Code Generator's documentation!
 ==============================================
 
+.. |license| image:: https://poser.pugx.org/gossi/php-code-generator/license
+	:target: https://packagist.org/packages/gossi/php-code-generator
+	:alt: License
+
+.. |version| image:: https://poser.pugx.org/gossi/php-code-generator/v/stable
+	:target: https://packagist.org/packages/gossi/php-code-generator
+	:alt: Latest Stable Version
+
+.. |downloads| image:: https://poser.pugx.org/gossi/php-code-generator/downloads
+	:target: https://packagist.org/packages/gossi/php-code-generator
+	:alt: Total Downloads
+
+
+.. |hhvm| image:: http://hhvm.h4cc.de/badge/gossi/php-code-generator.svg?style=flat
+	:target: http://hhvm.h4cc.de/package/gossi/php-code-generator
+	:alt: HHVM Status
+
+.. |build| image:: https://travis-ci.org/gossi/php-code-generator.svg?branch=master
+	:target: https://travis-ci.org/gossi/php-code-generator
+	:alt: Build Status
+
+.. |quality| image:: https://scrutinizer-ci.com/g/gossi/php-code-generator/badges/quality-score.png?b=master
+	:target: https://scrutinizer-ci.com/g/gossi/php-code-generator/?branch=master
+	:alt: Scrutinizer Code Quality
+
+.. |coverage| image:: https://scrutinizer-ci.com/g/gossi/php-code-generator/badges/coverage.png?b=master
+	:target: https://scrutinizer-ci.com/g/gossi/php-code-generator/?branch=master
+	:alt: Code Coverage
+
+.. |br| raw:: html
+
+   <br>
+
+|license| |version| |downloads| |br|
+|hhvm| |build| |quality| |coverage|
+
 This is a code generator for php code.
 
 Quickstart
diff --git a/docs/model.rst b/docs/model.rst
@@ -223,6 +223,51 @@ If you already have your class loaded, then you can use reflection to load your
   <?php
   use gossi\codegen\model\PhpClass;
 
-  $class = PhpClass::fromReflection(new \ReflectionClass('MyClass'));
+  $reflection = new \ReflectionClass('MyClass');
+  $class = PhpClass::fromReflection($reflection->getFileName());
 
 Also reflection is nice, there is a catch to it. You must make sure ``MyClass`` is loaded. Also all the requirements (use statements, etc.) are loaded as well, anyway you will get an error when initializing the the reflection object.
+
+Understanding Values
+--------------------
+
+The models ``PhpConstant``, ``PhpParameter`` and  ``PhpProperty`` support values; all of them implement the ``ValueInterface``. Though, there is a difference between values and expressions. Values refer to language primitives (``string``, ``int``, ``float``, ``bool`` and ``null``). Additionally you can set a ``PhpConstant`` as value (the lib understands this as a library primitive ;-). If you want more complex control over the output, you can set an expression instead, which will be generated as is.
+
+Some Examples::
+
+  <?php
+  PhpProperty::create('foo')->setValue('hello world.');
+  // $foo = 'hello world.';
+
+  PhpProperty::create('foo')->setValue(300);
+  // $foo = 300;
+
+  PhpProperty::create('foo')->setValue(3.14);
+  // $foo = 3.14;
+
+  PhpProperty::create('foo')->setValue(false);
+  // $foo = false;
+
+  PhpProperty::create('foo')->setValue(null);
+  // $foo = null;
+
+  PhpProperty::create('foo')->setValue(PhpConstant::create('BAR'));
+  // $foo = BAR;
+
+  PhpProperty::create('foo')->setExpression('self::MY_CONST');
+  // $foo = self::MY_CONST;
+
+  PhpProperty::create('foo')->setExpression("['my' => 'array']");
+  // $foo = ['my' => 'array'];
+
+For retrieving values there is a ``hasValue()`` method which returns ``true`` whether there is a value or an expression present. To be sure what is present there is also an ``isExpression()`` method which you can use as a second check::
+
+  <?php
+
+  if ($prop->hasValue()) {
+      if ($prop->isExpression()) {
+          // do something with an expression
+      } else {
+          // do something with a value
+      }
+  }
diff --git a/docs/static/style.css b/docs/static/style.css
@@ -0,0 +1,6 @@
+@import 'css/theme.css';
+
+.rst-content .section li > ol,
+.rst-content li > ol.arabic {
+	margin-bottom: 0;
+}
