add phpdoc to factory methods
misc doc block clean up