docs: first take on documenting api

README.md

@@ -13,50 +13,30 @@ It adds powerful layering functionality known from image editors, while staying
 
 **The project should be considered unstable for now, as I'm refactoring the code from an unhinged mess I made 10 years ago.**
 
+- [Getting started](docs/GettingStarted.md)
+- [Documentation](docs/Documentation.md)
+
 ## Example
-Create a heavily outdated meme with just a few lines of code.
+Here is a code adding watermark to an image:
 
 ```php
 use Naomai\PHPLayers\Image;
 
 // import image as background
-$layersImg = Image::createFromFile("eins.jpg");
+$layersImg = Image::createFromFile("stroller.jpg");
 
 // create a watermark layer from file, and move it to bottom left corner
-$watermarkLayer = $layersImg->newLayer()->importFromFile("cheesymemz.png");
+$watermarkLayer = $layersImg->newLayer()->importFromFile("lg_watermark.png");
 $watermarkLayer
     ->selectSurface()
     ->move(anchor: "bottom left")
     ->apply();
 
-// make things more THUG
-$thugLayer = $layersImg->newLayer()->importFromFile("thug.png");
-$thugLayer
-    ->selectSurface()
-    ->move(x: 290, y: 95)
-    ->apply();
-
 // export the image, and include it in the HTML file
 $dataUrl = $layersImg->export()->asDataUrl("webp");
 echo "<img src=\"".htmlspecialchars($dataUrl)."\"/><br/>";
 ```
 
-![Einstein with thug life glasses, watermarked](example/LayeringDemoResult.jpg)
-
-
-The image is made of 3 layers, including the background. If we add an extra line, we can show all the layers as a split view:
-
-```php
-// TiledComposer is putting all layers in a grid, instead of merging them
-$layersImg->setComposer(new PHPLayers\Composers\TiledComposer());
-
-$dataUrl = $layersImg->export()->asDataUrl("webp");
-echo "<img src=\"".htmlspecialchars($dataUrl)."\"/><br/>";
-```
-
-![Tiled view of indivitual layers making the Einstein thug life meme](example/LayeringDemoTiles.png)
-
-
 ## Use cases
 
 Previously developed as GDWrapper, was powering a rendering engine for

docs/Documentation.md

@@ -0,0 +1,79 @@
+# Documentation
+For readability, every class under PHPLayers namespace is referred using only its name. This is equivalent to placing `use Naomai\PHPLayers;` in the code.
+
+For example:
+
+- `Image` refers to fully-qualified name `Naomai\PHPLayers\Image`
+- `Generators\NonOverlappingText` refers to `Naomai\PHPLayers\Generators\NonOverlappingText`
+- `\InvalidArgumentException` is the builtin PHP class in global namespace
+
+## Image
+`Image` is the main class, holding everything needed to render the final image.
+
+### Creation
+`Image` can be instantiated using three ways:
+
+#### Constructor with size
+```php
+Image::__construct(int $width, int $height, $createLayer = true)
+```
+Create new image with given dimensions.
+
+If `createLayer` is true, a background layer is automatically created. This layer is fully transparent.
+
+```php
+$image = new Image(width: 50, height: 50, createLayer: true);
+$background = $image->getLayerByIndex(0);
+```
+
+#### createFromFile
+```php
+Image::createFromFile(string $fileName) : Image
+```
+Import image file into new PHP Layers Image object. The new image contains one layer with imported image as its content.
+
+`\RuntimeException` is thrown, if the file is not existing, or is not a valid image.
+
+**Returns** `Image` imported from file
+
+```php
+$image = Image::createFromFile("olympic.jpg");
+$background = $image->getLayerByIndex(0);
+```
+
+#### createFromGD
+```php
+Image::createFromGD(\GdImage $gdHandle) : Image
+```
+Wrap existing GD image into new PHP Layers Image object. The new image contains one layer with 
+its content **copied** from original image.
+
+```php
+$gdImage = imagecreatefromjpeg("olympic.jpg");
+$image = Image::createFromGD($gdImage);
+$background = $image->getLayerByIndex(0);
+```
+
+### Managing layers
+#### newLayer
+```php
+Image::newLayer(string $name=null) : Layer
+```
+Create new layer and put it on top of layer set. 
+
+Optional `name` is passed to internal `Layer::name` property that can be used in alternate layer composers, such as `Composers\TiledComposer`.
+
+```php
+$layerOne = $image->newLayer();
+```
+
+#### 
+```php
+Image::getLayerByIndex(int $id) : ?Layer
+```
+
+Gets the Layer object from layer set using its index.
+
+`id` is an index of the layer in Layer Stack. If negative, count from the last layer.
+
+**Returns** `Layer` object matching the index provided, or null if invalid.

docs/GettingStarted.md

@@ -0,0 +1,92 @@
+# Creating images
+## Overview
+The way we handle images in PHP is, honestly, really dated. Since the time of PHP/FI 2.0, which introduced GD image library in 1997, the language received support for objective programming. The support has matured quite a lot with recent PHP8 additions. Still, we're working on images using functions with long names, which at some point of time, became all-lowercase. Remember how we used to write ImageSetPixel instead of imagesetpixel?
+
+The evolution of built-in GD library is out of scope here. Instead, we're trying to reduce the boilerplate to minimum, and tackle some common pitfalls:
+
+- Why is my transparent background gone?
+- Is my semi-transparent rectangle going to paint over an image, or maybe punch a hole in it because it overwrites pixels?
+- I tried to merge two PNGs with 50% opacity. I used imagecopymerge, but now my transparency is gone.
+
+## Installation
+
+`php-layers` can be installed by using Composer.
+
+### Composer
+
+`php-layers` is currently only installable from Git, adding repository to your composer.json file:
+
+```json
+    "repositories": [
+        {
+            "url": "https://github.com/naomai/php-layers.git",
+            "type": "git"
+        }
+    ]
+```
+
+```shell
+    composer require twilio/sdk
+```
+
+Standalone and Packagist methods will be added in the future.
+
+### Test
+You can test your installation with a simple example.
+```php
+<?php
+use Naomai\PHPLayers;
+
+require_once __DIR__ . "/vendor/autoload.php";
+
+$testImage = new PHPLayers\Image(200, 50);
+$layer = $testImage->newLayer();
+$layer->paint()->text(x: 0, y: 0, text: "It Works!");
+$testImage->export()->toBrowser();
+
+```
+
+## Basic examples
+### Meme
+
+Create a heavily outdated meme with just a few lines of code.
+
+```php
+use Naomai\PHPLayers\Image;
+
+// import image as background
+$layersImg = Image::createFromFile("eins.jpg");
+
+// create a watermark layer from file, and move it to bottom left corner
+$watermarkLayer = $layersImg->newLayer()->importFromFile("cheesymemz.png");
+$watermarkLayer
+    ->selectSurface()
+    ->move(anchor: "bottom left")
+    ->apply();
+
+// make things more THUG
+$thugLayer = $layersImg->newLayer()->importFromFile("thug.png");
+$thugLayer
+    ->selectSurface()
+    ->move(x: 290, y: 95)
+    ->apply();
+
+// export the image, and include it in the HTML file
+$dataUrl = $layersImg->export()->asDataUrl("webp");
+echo "<img src=\"".htmlspecialchars($dataUrl)."\"/><br/>";
+```
+
+![Einstein with thug life glasses, watermarked](../example/LayeringDemoResult.jpg)
+
+
+The image is made of 3 layers, including the background. If we add an extra line, we can show all the layers as a split view:
+
+```php
+// TiledComposer is putting all layers in a grid, instead of merging them
+$layersImg->setComposer(new PHPLayers\Composers\TiledComposer());
+
+$dataUrl = $layersImg->export()->asDataUrl("webp");
+echo "<img src=\"".htmlspecialchars($dataUrl)."\"/><br/>";
+```
+
+![Tiled view of indivitual layers making the Einstein thug life meme](../example/LayeringDemoTiles.png)