GenerateMarkdownDoc
class GenerateMarkdownDoc extends BaseTask implements BuilderAwareInterface (View source)
Simple documentation generator from source files.
Takes classes, properties and methods with their docblocks and writes down a markdown file.
<?php
$this->taskGenDoc('models.md')
->docClass('Model\User') // take class Model\User
->docClass('Model\Post') // take class Model\Post
->filterMethods(function(\ReflectionMethod $r) {
return $r->isPublic() or $r->isProtected(); // process public and protected methods
})->processClass(function(\ReflectionClass $r, $text) {
return "Class ".$r->getName()."\n\n$text\n\n###Methods\n";
})->run();By default this task generates a documentation for each public method of a class, interface or trait. It combines method signature with a docblock. Both can be post-processed.
<?php
$this->taskGenDoc('models.md')
->docClass('Model\User')
->processClassSignature(false) // false can be passed to not include class signature
->processClassDocBlock(function(\ReflectionClass $r, $text) {
return "[This is part of application model]\n" . $text;
})->processMethodSignature(function(\ReflectionMethod $r, $text) {
return "#### {$r->name}()";
})->processMethodDocBlock(function(\ReflectionMethod $r, $text) {
return strpos($r->name, 'save')===0 ? "[Saves to the database]\n" . $text : $text;
})->run();Traits
Task input/output methods. TaskIO is 'used' in BaseTask, so any task that extends this class has access to all of the methods here.
Task input/output methods. TaskIO is 'used' in BaseTask, so any task that extends this class has access to all of the methods here.
Properties
| protected ConfigInterface | $config | from ConfigAwareTrait | |
| protected OutputAdapterInterface | $outputAdapter | from VerbosityThresholdTrait | |
| protected int | $verbosityThreshold | from VerbosityThresholdTrait | |
| protected OutputInterface | $output | from OutputAwareTrait | |
| protected TimeKeeper|null | $timer | from Timer | |
| protected null|ProgressIndicator | $progressIndicator | from ProgressIndicatorAwareTrait | |
| protected CollectionBuilder | $builder | from BuilderAwareTrait | |
| protected string[] | $docClass | ||
| protected callable | $filterMethods | ||
| protected callable | $filterClasses | ||
| protected callable | $filterProperties | ||
| protected callable | $processClass | ||
| protected callable|false | $processClassSignature | ||
| protected callable|false | $processClassDocBlock | ||
| protected callable|false | $processMethod | ||
| protected callable|false | $processMethodSignature | ||
| protected callable|false | $processMethodDocBlock | ||
| protected callable|false | $processProperty | ||
| protected callable|false | $processPropertySignature | ||
| protected callable|false | $processPropertyDocBlock | ||
| protected callable | $reorder | ||
| protected callable | $reorderMethods | ||
| protected callable | $reorderProperties | ||
| protected string | $filename | ||
| protected string | $prepend | ||
| protected string | $append | ||
| protected string | $text | ||
| protected string[] | $textForClass |
Methods
Any class that uses ConfigAwareTrait SHOULD override this method , and define a prefix for its configuration items. This is usually done in a base class. When used, this method should return a string that ends with a "."; see BaseTask::configPrefix().
No description
No description
Required verbosity level before any TaskIO output will be produced.
Print a message if the selected verbosity level is over this task's verbosity threshold.
Print information about a task in progress.
Provide notification that some part of the task succeeded.
Provide notification that there is something wrong, but execution can continue.
Provide notification that some operation in the task failed, and the task cannot continue.
Provide debugging notification. These messages are only displayed if the log level is VERBOSITY_DEBUG.
Get the formatted task name for use in task output.
Ask the provided parent class to inject all of the dependencies that it has and we need.
Take all dependencies availble to this task and inject any that are needed into the provided task. The general pattern is that, for every FooAwareInterface that this class implements, it should test to see if the child also implements the same interface, and if so, should call $child->setFoo($this->foo).
No description
No description
Put a class you want to be documented.
Using a callback function filter out methods that won't be documented.
Using a callback function filter out classes that won't be documented.
Using a callback function filter out properties that won't be documented.
Post-process class documentation.
Post-process class signature. Provide false to skip.
Post-process class docblock contents. Provide false to skip.
Post-process method documentation. Provide false to skip.
Post-process method signature. Provide false to skip.
Post-process method docblock contents. Provide false to skip.
Post-process property documentation. Provide false to skip.
Post-process property signature. Provide false to skip.
Post-process property docblock contents. Provide false to skip.
Use a function to reorder classes.
Use a function to reorder methods in class.
No description
No description
Inserts text at the beginning of markdown file.
Inserts text at the end of markdown file.
No description
No description
No description
No description
Details
$this
setConfig(ConfigInterface $config)
Set the config management object.
ConfigInterface
getConfig()
Get the config management object.
static protected string
configPrefix()
Any class that uses ConfigAwareTrait SHOULD override this method , and define a prefix for its configuration items. This is usually done in a base class. When used, this method should return a string that ends with a "."; see BaseTask::configPrefix().
static protected
configClassIdentifier($classname)
No description
static protected
configPostfix()
No description
static
configure(string $key, mixed $value, ConfigInterface|null $config = null)
No description
protected mixed|null
getConfigValue(string $key, mixed|null $default = null)
No description
$this
setVerbosityThreshold(int $verbosityThreshold)
Required verbosity level before any TaskIO output will be produced.
e.g. OutputInterface::VERBOSITY_VERBOSE
int
verbosityThreshold()
No description
setOutputAdapter(OutputAdapterInterface $outputAdapter)
No description
OutputAdapterInterface
outputAdapter()
No description
bool
hasOutputAdapter()
No description
bool
verbosityMeetsThreshold()
No description
writeMessage(string $message)
Print a message if the selected verbosity level is over this task's verbosity threshold.
$this
setOutput(OutputInterface $output)
No description
protected OutputInterface
output()
No description
protected OutputInterface
stderr()
No description
protected OutputInterface
getOutput()
deprecated
deprecated
Backwards compatibility
in
TaskIO at line 49
null|LoggerInterface
logger()
deprecated
deprecated
No description
in
TaskIO at line 85
protected
printTaskInfo(string $text, null|array $context = null)
Print information about a task in progress.
With the Symfony Console logger, NOTICE is displayed at VERBOSITY_VERBOSE and INFO is displayed at VERBOSITY_VERY_VERBOSE.
Robo overrides the default such that NOTICE is displayed at VERBOSITY_NORMAL and INFO is displayed at VERBOSITY_VERBOSE.
n.b. We should probably have printTaskNotice for our ordinary output, and use printTaskInfo for less interesting messages.
protected
printTaskSuccess(string $text, null|array $context = null)
Provide notification that some part of the task succeeded.
With the Symfony Console logger, success messages are remapped to NOTICE, and displayed in VERBOSITY_VERBOSE. When used with the Robo logger, success messages are displayed at VERBOSITY_NORMAL.
protected
printTaskWarning(string $text, null|array $context = null)
Provide notification that there is something wrong, but execution can continue.
Warning messages are displayed at VERBOSITY_NORMAL.
protected
printTaskError(string $text, null|array $context = null)
Provide notification that some operation in the task failed, and the task cannot continue.
Error messages are displayed at VERBOSITY_NORMAL.
protected
printTaskDebug($text, null|array $context = null)
Provide debugging notification. These messages are only displayed if the log level is VERBOSITY_DEBUG.
protected
printTaskOutput(string $level, string $text, null|array $context)
deprecated
deprecated
No description
protected bool
hideTaskProgress()
No description
protected
showTaskProgress(bool $inProgress)
No description
protected string
formatBytes(int $size, int $precision = 2)
Format a quantity of bytes.
protected string
getPrintedTaskName(null|object $task = null)
Get the formatted task name for use in task output.
This is placed in the task context under 'name', and used as the log label by Robo\Common\RoboLogStyle, which is inserted at the head of log messages by Robo\Common\CustomLogStyle::formatMessage().
protected array
getTaskContext(null|array $context = null)
No description
in
Timer at line 12
protected
startTimer()
No description
in
Timer at line 20
protected
stopTimer()
No description
in
Timer at line 28
protected
resetTimer()
No description
in
Timer at line 36
protected float|null
getExecutionTime()
No description
int
progressIndicatorSteps()
No description
$this
setProgressIndicator(null|ProgressIndicator $progressIndicator)
No description
protected null|bool
hideProgressIndicator()
No description
protected
showProgressIndicator()
No description
protected
restoreProgressIndicator(bool $visible)
No description
protected int
getTotalExecutionTime()
No description
protected
startProgressIndicator()
No description
protected bool
inProgress()
No description
protected
stopProgressIndicator()
No description
protected
disableProgressIndicator()
No description
protected
detatchProgressIndicator()
No description
protected
advanceProgressIndicator(int $steps = 1)
No description
$this
inflect(InflectionInterface|mixed $parent)
Ask the provided parent class to inject all of the dependencies that it has and we need.
injectDependencies(mixed $child)
Take all dependencies availble to this task and inject any that are needed into the provided task. The general pattern is that, for every FooAwareInterface that this class implements, it should test to see if the child also implements the same interface, and if so, should call $child->setFoo($this->foo).
The benefits of this are pretty large. Any time an object that implements
InflectionInterface is created, just call $child->inflect($this), and
any available optional dependencies will be hooked up via setter injection.
The required dependencies of an object should be provided via constructor injection, not inflection.
$this
setBuilder(CollectionBuilder $builder)
No description
CollectionBuilder
getBuilder()
No description
protected CollectionBuilder
collectionBuilder(ConsoleIO $io = null)
No description
static GenerateMarkdownDoc
init(string $filename)
No description
__construct(string $filename)
No description
$this
docClass(string $item)
Put a class you want to be documented.
$this
filterMethods(callable $filterMethods)
Using a callback function filter out methods that won't be documented.
$this
filterClasses(callable $filterClasses)
Using a callback function filter out classes that won't be documented.
$this
filterProperties(callable $filterProperties)
Using a callback function filter out properties that won't be documented.
$this
processClass(callable $processClass)
Post-process class documentation.
$this
processClassSignature(callable|false $processClassSignature)
Post-process class signature. Provide false to skip.
$this
processClassDocBlock(callable|false $processClassDocBlock)
Post-process class docblock contents. Provide false to skip.
$this
processMethod(callable|false $processMethod)
Post-process method documentation. Provide false to skip.
$this
processMethodSignature(callable|false $processMethodSignature)
Post-process method signature. Provide false to skip.
$this
processMethodDocBlock(callable|false $processMethodDocBlock)
Post-process method docblock contents. Provide false to skip.
$this
processProperty(callable|false $processProperty)
Post-process property documentation. Provide false to skip.
$this
processPropertySignature(callable|false $processPropertySignature)
Post-process property signature. Provide false to skip.
$this
processPropertyDocBlock(callable|false $processPropertyDocBlock)
Post-process property docblock contents. Provide false to skip.
$this
reorder(callable $reorder)
Use a function to reorder classes.
$this
reorderMethods(callable $reorderMethods)
Use a function to reorder methods in class.
$this
reorderProperties(callable $reorderProperties)
No description
$this
filename(string $filename)
No description
$this
prepend(string $prepend)
Inserts text at the beginning of markdown file.
$this
append(string $append)
Inserts text at the end of markdown file.
$this
text(string $text)
No description
$this
textForClass(string $item)
No description
Result
run()
No description
protected null|string
documentClass(string $class)
No description
protected string
documentClassSignature(ReflectionClass $reflectionClass)
No description
protected string
documentClassDocBlock(ReflectionClass $reflectionClass)
No description
protected string
documentMethod(ReflectionMethod $reflectedMethod)
No description
protected string
documentProperty(ReflectionProperty $reflectedProperty)
No description
protected string
documentPropertySignature(ReflectionProperty $reflectedProperty)
No description
protected string
documentPropertyDocBlock(ReflectionProperty $reflectedProperty)
No description
protected string
documentParam(ReflectionParameter $param)
No description
static string
indentDoc(string $doc, int $indent = 3)
No description
protected string
documentMethodSignature(ReflectionMethod $reflectedMethod)
No description
protected string
documentMethodDocBlock(ReflectionMethod $reflectedMethod)
No description
protected string
documentMethodParametersAndReturnType(ReflectionMethod $method, string $text)
No description
static string
stringifyNamedType(ReflectionNamedType $type, ReflectionClass $moduleClass)
No description