The facts expressed here belong to everybody, the opinions to me. The distinction is yours to draw.

Nooku framework rocks!

Everything is just great!

Check it out at http://nooku.org !

CREATE TABLE IF NOT EXISTS `#__harbour_boattypes` (
  `harbour_boattype_id` bigint(20) unsigned NOT NULL auto_increment,
  `title` varchar(255) NOT NULL,
  `enabled` tinyint(1) NOT NULL DEFAULT '1',

  ...

  `description` text COMMENT '@Filter("html, tidy")', # We are not pleased!

  ...

  `locked_on` datetime NOT NULL DEFAULT '0000-00-00 00:00:00',
  `locked_by` int(11) NOT NULL DEFAULT 0,
  PRIMARY KEY ( `harbour_boattype_id` )
) ENGINE=MyISAM  DEFAULT CHARSET=utf8;

Annotations?

• An annotation is a note that is made while reading any form of text.
• A note added in explanation, etc, esp of some literary work.

An essential part in our knowledge economy

• Law
• Linguistics
• Imaging
• Computational biology
• Software engineering

• Improve readability
• Influence run-time behavior of an application

An example: some Java code

@SuppressWarnings("fallthrough")
void myMethod(myVar)
{
    switch(myVar) {
            case 1:
                    doSomething();
            default:
                    doNothing();
    }
}

• No native support (yet)
• Solution: Reflection API!

<?php
$reflectionClass = new ReflectionClass("TestClass");

$methods = $reflectionClass->getMethods();
$properties = $reflectionClass->getProperties(ReflectionProperty::IS_PRIVATE);
$docblock = $reflectionClass->getDocComment(); /* Just what we need! */

What I've got so far

• LL(1) parser
• JSON-like syntax
• Supports booleans, strings, numbers, objects and arrays

So the following can now be validated properly:

<?php
class ComArticlesDatabaseTableArticles extends KDatabaseRowAbstract
{
        /** @filter("html", "tidy") */
        protected $introtext;

        ..

But we can go even further :

<?php
/**
 * My Nooku class representing a certain entity.
 *
 * @path("http://www.flickr.com/services/feeds/photos_public.gne?format=json")
 * @JSONP({callback="handle_data"})
 * @POST
 * @Persistent(false)
 * @Cachable(false)
 * @Behaviors('executable', 'orderable', 'nestable')
 * @deprecated
 */

Roll your own!

<?php
if($this->hasAnnotation('Shark')) {
        switch($this->getAnnotationValue('Shark')) {
                case 'hungry':
                        $this->makeMostCodeObsolete(); // this transatlantic flight
                        break;
                default:
                        $this->keepSwimming();
                        break;
        }
}

What's missing

• A working Nooku FW implementation .. for now!
• Useful benchmarking data
• A more practical example :-)

Do you feel like this when writing end-user documentation?

What if we could annotate DOM elements?

• Improving communication between team members of different skill types
• Creating helpful hints
• Eliminate Reduce time spent writing user documentation

Next phase

• Group annotations
• Create walkthrough out of groups
• Handle the queries in URL's

Final phase

• Save/load annotations to/from external location
• Toolbar button

• Steven Rombauts
• Find me on Twitter @kotuhaweb