Problem including source code

[neil-pearce]

Template issue/request

I am having an issue including source code in the generated documentation. It may well be that I do not understand the functionality but there appears to be some sort of issue.

If I use the default template there are not any files generated under the artifact name defined in templates\default\template.xml (ie files/{{path}}.txt). I believe that this is because the source file templates/default/source/file.source.txt.twig does not exists (I'm not sure why that twig file is defined under the sub-directory source but that is a different matter).

If I use the clean template then files are generated under the artifact name but they are all empty. That may be because the template.xml for clean refers to transformation writer="twig" whereas the writer is sourcecode for the default template.

As an aside, because of the PHAR it is difficult to make changes to test these theories but that may well be as a result of my ignorance!

• Version used: phpdocumentor-3.3.1
• Install method: PHIVE
• PHP version: PHP 8.1.4 (cli) (built: Mar 16 2022 09:33:31) (ZTS Visual C++ 2019 x64)
• Operating system and version: Windows 10

[jaapio]

Did you add the --sourcecode flag in your command?

[neil-pearce]

I have <include-source>true</include-source> in my phpdoc.dist.xml. Is that equivalent?

[jaapio]

it should be, however there could be a bug in this area :-) so I would like to ask you to give it a try.

[neil-pearce]

Thanks for this. I used the --sourcecode flag on the command line and things are starting to come together. With the default template some, but not all, of the source file were generated. All the source files were generated for the clean template. But in neither case did the files display - the error message ✖ Error: File does not exist, is empty or trying to view from localhost is displayed instead. I'll investigate a bit and get back to you on what I think may be happening. Many thanks for your help.

[neil-pearce]

I have a better idea of what is going on. As you have already explained you have to use the --sourcecode option.

Using the default template, anything that isn't a Class doesn't display the source code. The source-view logic is missing from the generated file for all cases other than Classes (eg a file containing a single function doesn't display the source code):

        <div class="phpdocumentor-modal" id="source-view">
    <div class="phpdocumentor-modal-bg" data-exit-button></div>
    <div class="phpdocumentor-modal-container">
        <div class="phpdocumentor-modal-content">
        <pre style="max-height: 500px; overflow-y: scroll" data-src="files/src/core/classes/Debug.php.txt" class="language-php line-numbers linkable-line-numbers"></pre>
        </div>
        <button data-exit-button class="phpdocumentor-modal__close">X</button>
    </div>
</div>

    <script type="text/javascript">
        function loadExternalCodeSnippets(line) {
            Array.prototype.slice.call(document.querySelectorAll('pre[data-src]')).forEach((pre) => {
                var src = pre.getAttribute('data-src').replace( /\\/g, '/');
                var extension = (src.match(/\.(\w+)$/) || [, ''])[1];
                var language = 'php';

                var code = document.createElement('code');
                code.className = 'language-' + language;

                pre.textContent = '';

                pre.setAttribute('data-line', line)
                code.textContent = 'Loading…';

                pre.appendChild(code);

                var xhr = new XMLHttpRequest();

                xhr.open('GET', src, true);

                xhr.onreadystatechange = function () {
                    if (xhr.readyState == 4) {

                        if (xhr.status < 400 && xhr.responseText) {
                            code.textContent = xhr.responseText;

                            Prism.highlightElement(code);
                        }
                        else if (xhr.status >= 400) {
                            code.textContent = '✖ Error ' + xhr.status + ' while fetching file: ' + xhr.statusText;
                        }
                        else {
                            code.textContent = '✖ Error: File does not exist, is empty or trying to view from localhost';
                        }
                    }
                };

                xhr.send(null);
            });
        }

        var modals = document.querySelectorAll("[data-modal]");

        modals.forEach(function (trigger) {
            trigger.addEventListener("click", function (event) {
                //event.preventDefault();
                const modal = document.getElementById(trigger.dataset.modal);
                modal.classList.add("phpdocumentor-modal__open");
                loadExternalCodeSnippets(trigger.dataset.line)
                const exits = modal.querySelectorAll("[data-exit-button]");
                exits.forEach(function (exit) {
                    exit.addEventListener("click", function (event) {
                        event.preventDefault();
                        modal.classList.remove("phpdocumentor-modal__open");
                    });
                });
            });
        });
    </script>

Using the clean template, once you have drilled down into a file (ie select the FILE option in the right hand menu) then the code is displayed correctly but it doesn't display when trying to view the source from the list of functions under the top-level ToC.

ENUMs are not documented using the clean template.

There isn't an issue to do with not all the files being generated, at least not one that I can reproduce, I'm afraid that you have to put that down to senility - I apologise for that.

[mvriel]

The issues that you described for the default template should be resolved through PR #3284.

As for the reported issue on the clean template; I haven't checked that out. But I do admit that issues in the default template have more priority for me as I only have so much time :)