doc: Added some documentation

.gitignore

@@ -0,0 +1 @@
+doc/api/

lib/spaceinvaders.dart

@@ -16,14 +16,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
+
+/// The classic Space Invaders game written in Dart.
 library spaceinvaders;
 
 import 'dart:collection';
 import 'dart:html' as dom;
 import 'dart:math' as math;
 
-import 'package:console_log_handler/console_log_handler.dart';
 import 'package:logging/logging.dart';
 
 part 'spaceinvaders/drawables.dart';

lib/spaceinvaders/FrameHandler.dart

@@ -21,6 +21,8 @@ part of spaceinvaders;
 
 enum Direction { Left, Right }
 
+/// Calls the [update]-Function every x-frames.
+/// The the intervall is defined via [updateFrequency]
 class FrameHandler {
     int _frames = 0;
     int _frequency = 30;

lib/spaceinvaders/InputHandler.dart

@@ -19,6 +19,7 @@
 
 part of spaceinvaders;
 
+/// Abstraction for keycodes typed by the user
 class KeyCode {
     final int code;
     const KeyCode(this.code);
@@ -32,6 +33,7 @@ class KeyCode {
     static const KeyCode Space = const KeyCode(32);
 }
 
+/// Listens for key pressed
 class InputHandler {
     final Logger _logger = new Logger('spaceinvaders.Sprites');
 

lib/spaceinvaders/Magazin.dart

@@ -19,6 +19,8 @@
 
 part of spaceinvaders;
 
+/// Magazin holds and fires all the [Bullet]s fire by either an [Alien]
+/// or by the [Tank]
 class Magazin {
     final List<Bullet> _bullets = new List<Bullet>();
 

lib/spaceinvaders/drawables.dart

@@ -19,37 +19,50 @@
 
 part of spaceinvaders;
 
+/// Base class for all the drawable (paintable) objects on the screen.
+///
+/// [Painter] uses this class for doing it's job
 abstract class Drawable {
+    /// The image that represents this [Drawable]
     Sprite get sprite;
+
     int get x;
     int get y;
 
     void draw(final Painter painter);
 }
 
+/// Mixin to move an object horizontally
 class MoveHorizontale {
     int x = 0;
     void moveLeft({ final int speed: 1}) { x -= speed; }
     void moveRight({ final int speed: 1}) { x += speed; }
 }
 
+/// Mixin to move an object vertically
 class MoveVertical{
     int y = 0;
     void moveUp({ final int speed: 1}) { y -= speed; }
     void moveDown({ final int speed: 1}) { y += speed; }
 }
 
+/// More or less a base implementation of [Drawable] plus
+/// with + height.
 abstract class ScreenObject implements Drawable {
 
     void draw(final Painter painter) { painter.draw(this); }
 
     int get width => sprite._width;
     int get height => sprite._height;
 
+    /// Describes the [Drawable] as [Rectangle]
     math.Rectangle<num> get rect => new math.Rectangle<num>(x,y,width,height);
+
+    /// Collision detection
     bool collidesWith(final ScreenObject so) => rect.intersects(so.rect);
 }
 
+/// The Tank can move left and right and shoots the [Alien]s
 class Tank extends ScreenObject with MoveHorizontale,MoveVertical implements Drawable {
     final Logger _logger = new Logger('spaceinvaders.Tank');
 
@@ -65,6 +78,7 @@ class Tank extends ScreenObject with MoveHorizontale,MoveVertical implements Dra
     Sprite get sprite => _sprite;
 }
 
+/// The enemy - the Aliens are organized in a [Swarm]
 class Alien extends ScreenObject implements Drawable {
     final Logger _logger = new Logger('spaceinvaders.Alien');
 
@@ -92,6 +106,7 @@ class Alien extends ScreenObject implements Drawable {
     }
 }
 
+/// Collection of [Alien]s
 class Swarm extends ScreenObject implements Drawable {
     final Logger _logger = new Logger('spaceinvaders.Swarm');
 
@@ -189,6 +204,7 @@ class Swarm extends ScreenObject implements Drawable {
         return new UnmodifiableListView<Alien>(aliens.where((final Alien alien) => !alien.killed));
     }
 
+    /// Looks for the frontmost [Alien]
     Alien closestAlien() {
         Alien closest;
         int yPos = 0;
@@ -227,6 +243,7 @@ class Swarm extends ScreenObject implements Drawable {
     }
 }
 
+/// City can be destroyed by [Alien]
 class City extends ScreenObject implements Drawable {
     final Logger _logger = new Logger('spaceinvaders.City');
     int x = 0;
@@ -241,6 +258,10 @@ class City extends ScreenObject implements Drawable {
     int get height => _sprite._height;
 }
 
+/// Holds (and draws!!!!) the [City] objects
+///
+/// Cities are drawn on [ImagePainter]. This makes it possible
+/// to destroy parts of a [City]
 class Cities extends ScreenObject implements Drawable {
     final Logger _logger = new Logger('spaceinvaders.Cities');
 
@@ -351,6 +372,8 @@ class Cities extends ScreenObject implements Drawable {
 
 }
 
+/// Bullet fired either by an [Alien] or by the [Tank].
+/// A [Magazin] is used to hold the [Bullet]s
 class Bullet extends ScreenObject with MoveVertical implements Drawable {
     final Logger _logger = new Logger('spaceinvaders.Bullet');
 

web/app/config.dart

@@ -19,6 +19,7 @@
 
 part of spaceinvaders.app;
 
+/// Minimal Log-Configuration
 void configLogging() {
     hierarchicalLoggingEnabled = false; // set this to true - its part of Logging SDK
 

web/app/init.dart

@@ -19,6 +19,8 @@
 
 part of spaceinvaders.app;
 
+/// Initializes the game - means sets the initial values for [FrameHandler] and so forth.
+/// Defines the base-positions for all the [Drawables] like [Tank], [Swarm]...
 void init(final FrameHandler frameHandler, final ScreenSize screensize, final SpriteFactory spritefactory) {
     frameHandler.updateFrequency = 30;
 

web/app/render.dart

@@ -19,12 +19,15 @@
 
 part of spaceinvaders.app;
 
+/// Draws all the [Drawables]. [Screen] returns a [Painter] that is used for
+/// all the drawing operations
 void render(final Screen screen,final SpriteFactory spritefactory) {
     screen.clear();
 
     final Painter painter = screen.painter;
 
     spritefactory.tank.draw(painter);
+
     spritefactory.swarm.draw(painter);
 
     spritefactory.cities.draw(painter);

web/app/update.dart

@@ -19,6 +19,8 @@
 
 part of spaceinvaders.app;
 
+/// All the properties will be updatet. X/Y positions, moving the swarm,
+/// firing [Bullet]s from the [Magazin]
 bool update(final FrameHandler frameHandler,final SpriteFactory spritefactory,
     final InputHandler inputHandler, final ScreenSize screensize) {
 
@@ -105,6 +107,7 @@ bool update(final FrameHandler frameHandler,final SpriteFactory spritefactory,
     }
 
     // Moves the sprites down (toggle)
+    // The frequency is defined in "init"
     frameHandler.update((final Direction direction) {
         spritefactory.swarm.toggle();
         direction == Direction.Left ? spritefactory.swarm.moveLeft() : spritefactory.swarm.moveRight();