From 5fb91994dac48cb8d80b3b86eb27779309bb21f2 Mon Sep 17 00:00:00 2001 From: Yury Bandarchuk Date: Sun, 12 Aug 2018 23:24:37 +0100 Subject: [PATCH 1/3] Add feature to raise error for undocumented definitions --- src/DocumentationBuilder.hh | 18 ++++--- src/DocumentationBuilderContext.hh | 6 +++ .../UndocumentedDefinitionException.hh | 33 +++++++++++++ src/GeneratorCLI.hh | 47 ++++++++++++++++--- 4 files changed, 91 insertions(+), 13 deletions(-) create mode 100644 src/Exceptions/UndocumentedDefinitionException.hh diff --git a/src/DocumentationBuilder.hh b/src/DocumentationBuilder.hh index 38a8d88..dbbf637 100644 --- a/src/DocumentationBuilder.hh +++ b/src/DocumentationBuilder.hh @@ -105,10 +105,15 @@ class DocumentationBuilder { protected function getDocumentationBody( Documentable $documentable, ): string { - $docs = DocBlock\DocBlock::nullable( - $documentable['definition']->getDocComment(), - ); $ctx = $this->getContext(); + $definition = $documentable['definition']; + $docs = DocBlock\DocBlock::nullable($definition->getDocComment()); + if ($docs === null && $ctx->shouldRaiseErrorOnUndocumentedDefinitions()) { + throw new Exceptions\UndocumentedDefinitionException( + $definition->getName(), + $definition->getFileName(), + ); + } $md = $this->getPageSections() |> Vec\map($$, $s ==> (new $s($ctx, $documentable, $docs))->getMarkdown()) |> Vec\filter_nulls($$) @@ -118,7 +123,7 @@ class DocumentationBuilder { $ast = Markdown\parse($parser_ctx, $md); $render_ctx = (new MarkdownExt\RenderContext()) - ->setOutputFormat($this->getContext()->getOutputFormat()) + ->setOutputFormat($ctx->getOutputFormat()) ->setDocumentable($documentable) ->setPathProvider( new IndexedPathProvider( @@ -130,9 +135,10 @@ class DocumentationBuilder { new MarkdownExt\AutoLinkifyFilter(), ); if ($ctx->IsSyntaxHighlightingOn()) { - $render_ctx = $render_ctx->appendFilters(new MarkdownExt\SyntaxHighlightingFilter()); + $render_ctx = + $render_ctx->appendFilters(new MarkdownExt\SyntaxHighlightingFilter()); } - switch ($this->getContext()->getOutputFormat()) { + switch ($ctx->getOutputFormat()) { case OutputFormat::MARKDOWN: $renderer = new Markdown\MarkdownRenderer($render_ctx); break; diff --git a/src/DocumentationBuilderContext.hh b/src/DocumentationBuilderContext.hh index fc4a8ac..6865510 100644 --- a/src/DocumentationBuilderContext.hh +++ b/src/DocumentationBuilderContext.hh @@ -25,6 +25,7 @@ class DocumentationBuilderContext { private Index $index, private IPathProvider $pathProvider, private bool $syntaxHighlightingOn, + private bool $raiseErrorOnUndocumentedDefinitions, ) { } @@ -48,4 +49,9 @@ class DocumentationBuilderContext { return $this->syntaxHighlightingOn; } + /** @selfdocumenting */ + public function shouldRaiseErrorOnUndocumentedDefinitions(): bool { + return $this->raiseErrorOnUndocumentedDefinitions; + } + } diff --git a/src/Exceptions/UndocumentedDefinitionException.hh b/src/Exceptions/UndocumentedDefinitionException.hh new file mode 100644 index 0000000..de1261c --- /dev/null +++ b/src/Exceptions/UndocumentedDefinitionException.hh @@ -0,0 +1,33 @@ +> + public function __construct( + private string $fieldname, + private string $fileName, + ) {} + + <<__Override>> + public function getMessage(): string { + return "Error while generating documentation: ". + "Undocumented definition '". + $this->fieldname. + "' found ". + "at path: ". + $this->fileName."\n"; + } +} diff --git a/src/GeneratorCLI.hh b/src/GeneratorCLI.hh index 2f98910..3c26165 100644 --- a/src/GeneratorCLI.hh +++ b/src/GeneratorCLI.hh @@ -34,6 +34,7 @@ final class GeneratorCLI extends CLIWithRequiredArguments { private ?string $outputRoot = null; private int $verbosity = 0; private bool $syntaxHighlightingOn = true; + private bool $raiseErrorOnUndocumentedDefinitions = false; <<__Override>> protected function getSupportedOptions(): vec { @@ -69,6 +70,14 @@ final class GeneratorCLI extends CLIWithRequiredArguments { '--no-highlighting', '-n', ), + CLIOptions\flag( + () ==> { + $this->raiseErrorOnUndocumentedDefinitions = true; + }, + "Raise error on undocumented definitions", + '--no-undoc-definitions', + '-u', + ), ]; } @@ -95,7 +104,13 @@ final class GeneratorCLI extends CLIWithRequiredArguments { $index = create_index($documentables); $paths = new SingleDirectoryPathProvider($extension); - $context = new DocumentationBuilderContext($this->format, $index, $paths, $this->syntaxHighlightingOn); + $context = new DocumentationBuilderContext( + $this->format, + $index, + $paths, + $this->syntaxHighlightingOn, + $this->raiseErrorOnUndocumentedDefinitions, + ); $md_builder = new DocumentationBuilder($context); if ($this->outputRoot === null) { @@ -111,12 +126,30 @@ final class GeneratorCLI extends CLIWithRequiredArguments { } $this->getStdout()->write("Generating documentation...\n"); - foreach ($documentables as $documentable) { - $content = $md_builder->getDocumentation($documentable); - $path = get_path_for_documentable($paths, $documentable); - \file_put_contents($prefix.$path, $content); - $this->verboseWrite($path."\n"); - } + + $documentations = Map {}; + Vec\map( + $documentables, + ($documentable) ==> { + $path = get_path_for_documentable($paths, $documentable); + $this->verboseWrite($path."\n"); + try { + $documentation = $md_builder->getDocumentation($documentable); + $documentations[$path] = $documentation; + } catch (Exceptions\UndocumentedDefinitionException $e) { + $this->getStderr()->write($e->getMessage()); + \exit(1); + } + }, + ); + + Vec\map_with_key( + $documentations, + ($path, $content) ==> { + \file_put_contents($prefix.$path, $content); + }, + ); + $this->getStdout()->write("Creating index document...\n"); \file_put_contents( $prefix.'index'.$extension, From 0194324a8147a998965ebaffb2054a2aca169c8a Mon Sep 17 00:00:00 2001 From: Yury Bandarchuk Date: Sun, 12 Aug 2018 23:33:08 +0100 Subject: [PATCH 2/3] Fix Travis --- src/Exceptions/UndocumentedDefinitionException.hh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/Exceptions/UndocumentedDefinitionException.hh b/src/Exceptions/UndocumentedDefinitionException.hh index de1261c..f8fc668 100644 --- a/src/Exceptions/UndocumentedDefinitionException.hh +++ b/src/Exceptions/UndocumentedDefinitionException.hh @@ -19,7 +19,9 @@ final class UndocumentedDefinitionException extends \Exception { public function __construct( private string $fieldname, private string $fileName, - ) {} + ) { + parent::__construct(); + } <<__Override>> public function getMessage(): string { From d945d2a4e09f50c7be89703f7af3141e820a5b0b Mon Sep 17 00:00:00 2001 From: Yury Bandarchuk Date: Sun, 12 Aug 2018 23:37:46 +0100 Subject: [PATCH 3/3] Update documentatin --- ...cumentationBuilderContext.__construct.html | 2 + ....HHAPIDoc.DocumentationBuilderContext.html | 3 +- ...ldRaiseErrorOnUndocumentedDefinitions.html | 45 +++++++++++++++++ ...mentedDefinitionException.__construct.html | 49 ++++++++++++++++++ ...umentedDefinitionException.getMessage.html | 45 +++++++++++++++++ ...tions.UndocumentedDefinitionException.html | 50 +++++++++++++++++++ docs/index.html | 1 + 7 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.shouldRaiseErrorOnUndocumentedDefinitions.html create mode 100644 docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.__construct.html create mode 100644 docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.getMessage.html create mode 100644 docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.html diff --git a/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.__construct.html b/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.__construct.html index e5de06e..444d7a6 100644 --- a/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.__construct.html +++ b/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.__construct.html @@ -40,6 +40,7 @@

Facebook\HHAPIDoc\DocumentationBuilderContext::__construct()

Facebook\HHAPIDoc\Index $index, IPathProvider<?string> $pathProvider, bool $syntaxHighlightingOn, + bool $raiseErrorOnUndocumentedDefinitions, );

Parameters

@@ -50,6 +51,7 @@

Parameters

  • IPathProvider<?string> $pathProvider a path provider that returns paths for documentables that exist, or null for ones that don't.
  • bool $syntaxHighlightingOn
    • +
  • bool $raiseErrorOnUndocumentedDefinitions
    • diff --git a/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.html b/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.html index fc58ea4..c43594e 100644 --- a/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.html +++ b/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.html @@ -43,11 +43,12 @@

    Interface Synopsis

    Public Methods

    diff --git a/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.shouldRaiseErrorOnUndocumentedDefinitions.html b/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.shouldRaiseErrorOnUndocumentedDefinitions.html new file mode 100644 index 0000000..2e4405a --- /dev/null +++ b/docs/class.Facebook.HHAPIDoc.DocumentationBuilderContext.shouldRaiseErrorOnUndocumentedDefinitions.html @@ -0,0 +1,45 @@ + + +Facebook\HHAPIDoc\DocumentationBuilderContext::shouldRaiseErrorOnUndocumentedDefinitions + + + +

    Facebook\HHAPIDoc\DocumentationBuilderContext::shouldRaiseErrorOnUndocumentedDefinitions()

    +
    public function shouldRaiseErrorOnUndocumentedDefinitions(): bool;
    + +

    Returns

    +
      +
    • bool
      • +
    + + + \ No newline at end of file diff --git a/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.__construct.html b/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.__construct.html new file mode 100644 index 0000000..fc9f04f --- /dev/null +++ b/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.__construct.html @@ -0,0 +1,49 @@ + + +Facebook\HHAPIDoc\Exceptions\UndocumentedDefinitionException::__construct + + + +

    Facebook\HHAPIDoc\Exceptions\UndocumentedDefinitionException::__construct()

    +
    public function __construct(
+  string $fieldname,
+  string $fileName,
+);
    + +

    Parameters

    +
      +
    • string $fieldname
      • +
    • string $fileName
      • +
    + + + \ No newline at end of file diff --git a/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.getMessage.html b/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.getMessage.html new file mode 100644 index 0000000..4cf3003 --- /dev/null +++ b/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.getMessage.html @@ -0,0 +1,45 @@ + + +Facebook\HHAPIDoc\Exceptions\UndocumentedDefinitionException::getMessage + + + +

    Facebook\HHAPIDoc\Exceptions\UndocumentedDefinitionException::getMessage()

    +
    public function getMessage(): string;
    + +

    Returns

    +
      +
    • string
      • +
    + + + \ No newline at end of file diff --git a/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.html b/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.html new file mode 100644 index 0000000..c3adb59 --- /dev/null +++ b/docs/class.Facebook.HHAPIDoc.Exceptions.UndocumentedDefinitionException.html @@ -0,0 +1,50 @@ + + +Facebook\HHAPIDoc\Exceptions\UndocumentedDefinitionException + + + +

    Facebook\HHAPIDoc\Exceptions\UndocumentedDefinitionException

    +

    Exception thrown on undocumented definition

    +

    Interface Synopsis

    +
    namespace Facebook\HHAPIDoc\Exceptions;
+
+final class UndocumentedDefinitionException extends \Exception {...}
    + +

    Public Methods

    + + + + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index ed7dd01..471e200 100644 --- a/docs/index.html +++ b/docs/index.html @@ -20,6 +20,7 @@

    Classes

  • Facebook\HHAPIDoc\DocBlock\DocBlock
  • Facebook\HHAPIDoc\DocumentationBuilder
  • Facebook\HHAPIDoc\DocumentationBuilderContext
    • +
  • Facebook\HHAPIDoc\Exceptions\UndocumentedDefinitionException
  • Facebook\HHAPIDoc\GeneratorCLI
  • Facebook\HHAPIDoc\IndexDocumentBuilder
  • Facebook\HHAPIDoc\IndexedPathProvider