Merge pull request #3539 from phpDocumentor/feature/filesource-tag

Feature/filesource tag
phpDocumentor · Jul 20, 2023 · 22fe75f · 22fe75f
2 parents 1746d03 + 52bb1b1
commit 22fe75f
Show file tree

Hide file tree

Showing 10 changed files with 82 additions and 41 deletions.
diff --git a/data/templates/default/components/element-found-in.html.twig b/data/templates/default/components/element-found-in.html.twig
@@ -4,6 +4,6 @@
     <span class="phpdocumentor-element-found-in__line">{{ node.line }}</span>
 
     {% if node.file.source %}
-        <a href="{{ target_path }}#source-view.{{ node.line }}" class="phpdocumentor-element-found-in__source" data-line="{{ node.line }}" data-modal="source-view" data-src="{{ path('files/' ~ node.path ~ '.txt')|raw }}"></a>
+        <a href="{{ target_path }}#source-view.{{ node.line }}" class="phpdocumentor-element-found-in__source" data-line="{{ node.line }}" data-modal="source-view" data-src="{{ path('files/' ~ node.file.path ~ '.txt')|raw }}"></a>
     {% endif %}
 </aside>
diff --git a/docs/references/full-config-reference.rst b/docs/references/full-config-reference.rst
@@ -78,7 +78,7 @@ folder
 **Default**
 
 .. code-block:: xml
-  
+
 apis
 ~~~~
 
@@ -103,7 +103,7 @@ visibilities
 Visibilities are setting the deepest level of elements that will be rendered in your documentation. The values can be
 combined to fine tune the output. By default phpDocumentor includes all elements unless they are marked as ``@internal``
 
-Api will render only the elements marked as part of your api using the ``@api`` tag. 
+Api will render only the elements marked as part of your api using the ``@api`` tag.
 Public will filter all public elements from your project and render them in to the documentation.
 Protected will filter all public elements from your project and render them in to the documentation.
 Private will filter all public elements from your project and render them in to the documentation.
@@ -141,20 +141,20 @@ source
 ``````
 
 Where should phpDocumentor start looking for your code? In this configration section you can configure the DSN to your
-code base. 
+code base.
 
 The source can be configured using 2 parts. DSN which points to the root of your code base and paths which specify which
 folders should be read. Paths can be used to be more specific which folders should be included. All other paths in the root
-will be ignored. 
+will be ignored.
 
 .. note::
    Future versions of phpDocumentor will support other DSN formats rather then just local paths. Right now only
    `file://` is supported
 
-Paths do support glob patterns to be able to include only particular sub directories. 
+Paths do support glob patterns to be able to include only particular sub directories.
 The example below will only include files in your DSN root directory `src` and it's sub directories, when the file name matches
 `*Interface.php`
- 
+
 .. code-block:: xml
    <path>/src/**/*Interface.php</path>
 
@@ -213,17 +213,22 @@ include-source
 
 Should phpDocumentor include your source code in the rendered documentation? By including your source code people reading
 your docs can jump directly from the docs to a rendered version of the source code. Which allows them to get more details about
-a method or function implementation. 
+a method or function implementation.
+
+By default source code is not included in the rendered documentation.
+Unless the file contains a :doc:`@filesource <./phpdoc/tags/filesource>` tag.
+
+This setting can be overridden by using the ``--sourcecode`` or ``--no-sourcecode`` command line option.
 
 **Default**
 
 .. code-block:: xml
-   true
+   null
 
 examples
 ````````
 
-Examples are code snippets that can be included in your docblocks. This setting will configure where phpDocumentor 
+Examples are code snippets that can be included in your docblocks. This setting will configure where phpDocumentor
 can find them. The paths used in your docblock ``@example`` tags are relative to this dsn.
 For more information about ``@example`` please consult the tag reference.
 
@@ -264,20 +269,20 @@ source
 ``````
 
 Where should phpDocumentor start looking for your code? In this configuration section you can configure the DSN to your
-code base. 
+code base.
 
 The source can be configured using 2 parts. DSN which points to the root of your code base and paths which specify which
 folders should be read. Paths can be used to be more specific which folders should be included. All other paths in the root
-will be ignored. 
+will be ignored.
 
 .. note::
    Future versions of phpDocumentor will support other DSN formats rather then just local paths. Right now only
    `file://` is supported
 
-Paths do support glob patterns to be able to include only particular sub directories. 
+Paths do support glob patterns to be able to include only particular sub directories.
 The example below will only include files in your DSN root directory ``src`` and it's sub directories, when the file
 name matches ``*Interface.php``
- 
+
 .. code-block:: xml
    <path>/src/**/*Interface.php</path>
 
@@ -306,8 +311,8 @@ output
 settings
 --------
 
-Some settings are not part of the normal configuration parts of phpDocumentor. Because there have impact 
-on the full application behavior, or enable experimental parts in phpDocumentor. 
+Some settings are not part of the normal configuration parts of phpDocumentor. Because there have impact
+on the full application behavior, or enable experimental parts in phpDocumentor.
 
 Settings are key-value configuration options, which are listed with the following command:
 

diff --git a/src/phpDocumentor/Compiler/ApiDocumentation/Pass/RemoveSourcecode.php b/src/phpDocumentor/Compiler/ApiDocumentation/Pass/RemoveSourcecode.php
@@ -32,6 +32,10 @@ protected function process(ApiSetDescriptor $subject): ApiSetDescriptor
         }
 
         foreach ($subject->getFiles() as $file) {
+            if ($subject->getSettings()['include-source'] !== false && $file->getTags()->fetch('filesource') !== null) {
+                continue;
+            }
+
             $file->setSource(null);
         }
 

diff --git a/src/phpDocumentor/Configuration/ApiSpecification.php b/src/phpDocumentor/Configuration/ApiSpecification.php
@@ -54,7 +54,7 @@ final class ApiSpecification implements ArrayAccess
     /** @var string */
     private $defaultPackageName;
 
-    /** @var bool */
+    /** @var bool|null */
     private $includeSource;
 
     /** @var array<string> */
@@ -86,7 +86,7 @@ private function __construct(
         array $extensions,
         array $visibility,
         string $defaultPackageName,
-        bool $includeSource,
+        bool|null $includeSource,
         array $markers,
         array $ignoreTags,
         ?Source $examples,
@@ -155,7 +155,7 @@ public static function createDefault(): ApiSpecification
             ['php'],
             [],
             '',
-            false,
+            null,
             [],
             [],
             null,

diff --git a/src/phpDocumentor/Configuration/Definition/Version3.php b/src/phpDocumentor/Configuration/Definition/Version3.php
@@ -302,7 +302,7 @@ private function apiSection(): ArrayNodeDefinition
                         ->end()
                     ->end()
                     ->booleanNode('include-source')
-                        ->defaultTrue()
+                        ->defaultNull()
                     ->end()
                     ->arrayNode('examples')
                         ->fixXmlConfig('path')

diff --git a/src/phpDocumentor/Console/Command/Project/RunCommand.php b/src/phpDocumentor/Console/Command/Project/RunCommand.php
@@ -231,7 +231,7 @@ protected function configure(): void
             ->addOption(
                 'sourcecode',
                 null,
-                InputOption::VALUE_NONE,
+                InputOption::VALUE_NONE | InputOption::VALUE_NEGATABLE,
                 'Whether to include syntax highlighted source code'
             )
             ->addOption(

diff --git a/src/phpDocumentor/Transformer/Writer/Sourcecode.php b/src/phpDocumentor/Transformer/Writer/Sourcecode.php
@@ -50,10 +50,7 @@ public function transform(
         ProjectDescriptor $project,
         DocumentationSetDescriptor $documentationSet
     ): void {
-        if (
-            $documentationSet instanceof ApiSetDescriptor === false ||
-            $documentationSet->getSettings()['include-source'] === false
-        ) {
+        if ($documentationSet instanceof ApiSetDescriptor === false) {
             return;
         }
 

diff --git a/tests/unit/phpDocumentor/Compiler/ApiDocumentation/Pass/RemoveSourcecodeTest.php b/tests/unit/phpDocumentor/Compiler/ApiDocumentation/Pass/RemoveSourcecodeTest.php
@@ -36,6 +36,21 @@ public function testRemovesSourceWhenDisabled(): void
     {
         $apiSetDescriptor = $this->faker()->apiSetDescriptor();
         $apiSetDescriptor = $this->givenFiles($apiSetDescriptor);
+        $apiSetDescriptor->getSettings()['include-source'] = false;
+        $fixture = new RemoveSourcecode();
+
+        $fixture->__invoke($apiSetDescriptor);
+
+        foreach ($apiSetDescriptor->getFiles() as $file) {
+            self::assertNull($file->getSource());
+        }
+    }
+
+    public function testRemovesSourceWhenNotSet(): void
+    {
+        $apiSetDescriptor = $this->faker()->apiSetDescriptor();
+        $apiSetDescriptor = $this->givenFiles($apiSetDescriptor);
+        $apiSetDescriptor->getSettings()['include-source'] = null;
         $fixture = new RemoveSourcecode();
 
         $fixture->__invoke($apiSetDescriptor);
@@ -62,6 +77,41 @@ public function testRemovesSourceWhenSourceShouldBeIncluded(): void
         }
     }
 
+    public function testSourceIsIncludedWhenFilesourceTagIsPresent(): void
+    {
+        $apiSetDescriptor = $this->faker()->apiSetDescriptor();
+        $apiSetDescriptor = $this->givenFiles($apiSetDescriptor);
+        $apiSetDescriptor->getFiles()->first()->getTags()->set(
+            'filesource',
+            $this->faker()->fileDescriptor()
+        );
+        $fixture = new RemoveSourcecode();
+
+        $fixture->__invoke($apiSetDescriptor);
+
+        foreach ($apiSetDescriptor->getFiles() as $file) {
+            self::assertNotNull($file->getSource());
+        }
+    }
+
+    public function testSourceIsRemovedWhenSettingDisabledExplicitly(): void
+    {
+        $apiSetDescriptor = $this->faker()->apiSetDescriptor();
+        $apiSetDescriptor = $this->givenFiles($apiSetDescriptor);
+        $apiSetDescriptor->getSettings()['include-source'] = false;
+        $apiSetDescriptor->getFiles()->first()->getTags()->set(
+            'filesource',
+            $this->faker()->fileDescriptor()
+        );
+        $fixture = new RemoveSourcecode();
+
+        $fixture->__invoke($apiSetDescriptor);
+
+        foreach ($apiSetDescriptor->getFiles() as $file) {
+            self::assertNull($file->getSource());
+        }
+    }
+
     private function givenFiles(ApiSetDescriptor $apiDescriptor): ApiSetDescriptor
     {
         $apiDescriptor->setFiles(

diff --git a/tests/unit/phpDocumentor/Configuration/Definition/Version3Test.php b/tests/unit/phpDocumentor/Configuration/Definition/Version3Test.php
@@ -184,7 +184,7 @@ private function defaultConfigurationOutput(): array
                             'extensions' => [
                                 'extensions' => ['php', 'php3', 'phtml'],
                             ],
-                            'include-source' => true,
+                            'include-source' => false,
                             'validate' => false,
                             'markers' => ['markers' => ['TODO', 'FIXME']],
                             'ignore-tags' => ['ignore_tags' => []],

diff --git a/tests/unit/phpDocumentor/Transformer/Writer/SourcecodeTest.php b/tests/unit/phpDocumentor/Transformer/Writer/SourcecodeTest.php
@@ -49,20 +49,6 @@ protected function setUp(): void
         );
     }
 
-    /**
-     * @covers ::transform
-     */
-    public function testNoInteractionWithTransformationWhenSourceShouldNotIncluded(): void
-    {
-        $transformation = $this->prophesize(Transformation::class);
-        $transformation->template()->shouldNotBeCalled();
-
-        $apiSet = $this->faker()->apiSetDescriptor();
-        $projectDescriptor = $this->giveProjectDescriptor($apiSet);
-
-        $this->sourceCode->transform($transformation->reveal(), $projectDescriptor, $apiSet);
-    }
-
     /**
      * @covers ::transform
      */
@@ -72,7 +58,6 @@ public function testNoInteractionWithTransformationWhenSourceIsIncluded(): void
         $transformation->template()->shouldBeCalled()->willReturn($this->faker()->template());
 
         $api = $this->faker()->apiSetDescriptor();
-        $api->getSettings()['include-source'] = true;
         $projectDescriptor = $this->giveProjectDescriptor($api);
 
         $this->sourceCode->transform($transformation->reveal(), $projectDescriptor, $api);