Hi there,
i have not found any useful information on my question.

Situation:

/**
 * [Description for testFunction]
 *
 * @param   string  $argument1
 * @param   array   $options
 *
 * @return  void
 */
function testFunction(string $argument1 = "", array $options)
{
	// simple definition of defaults
	$options["property1"] = $options["property1"] ?? "defaultValueForProperty1";
	$options["property2"] = $options["property2"] ?? "defaultValueForProperty2";
	$options["property3"] = $options["property3"] ?? "defaultValueForProperty3";
}

2 Questions at the Moment:
How i document the default for $argument1 correctly?
How i document the available properties (type, name, default, description) for $options correctly?

For the second question was my first idea (but i thinks its not working correctly):

/**
 * Description for testFunction
 *
 * @param   string  $argument1
 * @param   array   $options{
 *  property1:  ?string     defaultValueForProperty1    Description for defaultValueForProperty1.
 *  property2:  ?string     defaultValueForProperty2    Description for defaultValueForProperty2.
 *  property3:  ?string     defaultValueForProperty2    Description for defaultValueForProperty3.
 * }
 *
 * @return  void
 */
function testFunction(string $argument1 = "", array $options)
{
	// simple definition of defaults
	$options["property1"] = $options["property1"] ?? "defaultValueForProperty1";
	$options["property2"] = $options["property2"] ?? "defaultValueForProperty2";
	$options["property3"] = $options["property3"] ?? "defaultValueForProperty1";
}

Result:

Thank you so much!

Missing a $ in front of a property name breaks the transformer.

Expected behavior

Do not crash when processing a comment missing the $. Skip it maybe?

Actual behavior

phpDocumentor crashes with this error:

CRITICAL [console] An error occurred while using the console. Message: "Call to a member function getFile() on null" ["exception" => Error { …},"message" => "Call to a member function getFile() on null"]

In PropertyDescriptor.php line 118:

Call to a member function getFile() on null

Steps to reproduce the problem

/**

• Do Something
• This breaks phpDocumentor.
• @Property AClass AProperty The property
  */
  class ABC {}

/**

• Do Something
• This works.
• @Property AClass $AProperty The property
  */
  class ABC {}

Your environment

• Version used: 3.0.0
• Install method: Docker container
• PHP version: 8
• Operating system and version (e.g. Ubuntu 20.04, Windows 10): MacOS

See phpDocumentor Web Pages Are Not Styled for a full write up on this and other phpDocumentor issues.

This breaks...

/**

• Export locations to a CSV file.
• @property-read array $active_columns;
• @property-read string[] $dbFields The fields we want to export.
  */
  class SLP_Power_Locations_Export {}

This works...

/**

• Export locations to a CSV file.
• @property-read array $active_columns
• @property-read string[] $dbFields The fields we want to export.
  */
  class SLP_Power_Locations_Export

Expected behavior

An errant semicolon on a property description should not crash the entire documentor run.

Actual behavior

5/22 [======>---------------------] 22%04:22:21 CRITICAL [console] An error occurred while using the console. Message: "Call to a member function getFile() on null" ["exception" => Error { …},"message" => "Call to a member function getFile() on null"]

In PropertyDescriptor.php line 118:

Call to a member function getFile() on null

Steps to reproduce the problem

1. Add a semicolon to a property description
2. Run the documentor tool (via Docker, but it probably happens on all installs)

Your environment

• Version used: 3
• Install method: Docker
• PHP version: 8
• Operating system and version (e.g. Ubuntu 20.04, Windows 10): MacOS (latest)
• ...

Expected behavior

Working link to tags page per doc source.

Actual behavior

Steps to reproduce the problem

1. Go to https://docs.phpdoc.org/3.0/guide/references/phpdoc/inline-tags/index.html

Your environment

N/A

Hello, I've been using the guide feature, I'm happy because I can put hand written docs in the same place for the generated docs (it's also reduce confusion to readers). I'm aware that it's still experimental, but I have question about:

1. The output dir, I'd like to set the hand written docs in the root path instead of being in sub directory, i tried to adjust it from the configuration but no luck. This may be no issue for those who host the docs in web servers, but not for those who host the docs in github pages since it's almost impossible to make redirect rule.
2. Search function, the search in phpDocumentor seems do not look up results for the hand written guides, not sure if I need to set up something for that?
3. Markdown support, it is mentioned in https://docs.phpdoc.org/3.0/guide/hand-written-docs/index.html that Markdown is supported, but i looked again here it's still work in progress, i hope that can happen soon since I'm not familiar writing with reStructuredText, the syntax is not that easy and external tools out there requires me to set up Python, they are mostly for writing Sphinx docs, so that I'm not sure the syntax will be even understood by phpDocumentor, not just that, the syntax is not friendly with php codes, like i have to escape every underscore when mentioning a php snake case variables
4. Table borders, it's weird to have table without any borders.
5. Also how do I embed image from external link?

Thank you.

Expected behavior

phpDocumentor will be installed.

Steps to reproduce the problem

1. "composer.json":

{
    "minimum-stability": "dev",
    "config": {
        "platform": {
            "php": "7.4"
        }
    },
    "require-dev": {
        "phpdocumentor/phpdocumentor": "3.3.*"
    }
}

composer update outputs phpdocumentor/phpdocumentor[v3.3.0, ..., v3.3.1] require phpdocumentor/guides-markdown *@dev -> could not be found in any version, there may be a typo in the package name.

2. "composer.json":

{
    "minimum-stability": "dev",
    "config": {
        "platform": {
            "php": "7.4"
        }
    },
    "repositories": [
        {
            "type": "vcs",
            "url":  "https://github.com/phpDocumentor/guides-markdown"
        }
    ],
    "require-dev": {
        "phpdocumentor/phpdocumentor": "3.3.*"
    }
}

composer update outputs league/uri[6.8.0, ..., 6.x-dev] require php ^8.1 -> your php version (7.4; overridden via config.platform, actual: 7.4.33) does not satisfy that requirement.

Environment

• Version used: 3.3.*
• Install method: Composer 2.4.4
• PHP 7.4.33
• Operating system: Windows 10
• My project: https://github.com/deepeloper/pdo-debugging

When I use the :php:class: or any of the other :php: references, then a correct path seems be rendered but I and up on the path file://wsl%24/classes/ instead of the correct file location.

During a recent change something broke in in the service definitions, causing guides to fatally error. Despite this, the docker image was built and pushed onto our registry. This can impact our users as build pipelines could fail.

In order to make our delivery pipeline more stable, we should run the docker image with guides enabled against our own documentation before pushing the image onto the registry. This should at least be a smoke test that running phpDocumentor, including guides, works.

The current smoke tests cannot have guides enabled at the moment because plantuml is not installed as a dependency; it would also be nice to have these smoke tests run guides.

Can we tag/release version 3.3.2 (or whatever the next version should be)? I would like to use the fix from #3244 in my application!

Thank you!

When rendering RestructuredText components and using an admonition (such as "note", "important", etc); these are not rendered at all and styling is missing.

After this issue, admonitions should

1. render
2. be styled
3. Contain an icon showing the type of admonition

When you define a title with an underscore in it, you do not see it in the rendered output and it is not used in the anchor; thus linking to it won't work either.

Repro:

My_Title
=======

`My_Title`_ does not work

In the repro above it will render as MyTitle and the internal target doesn't resolve

Expected behavior

Content of the .. note:: directive should be rendered

Actual behavior

We see the raw rST content there.

Steps to reproduce the problem

1. Go on https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/param.html#effects-in-phpdocumentor
2. Look at phpstan or psalm links inside the note

Your environment

Whatever was used to build the phpdoc.org website

Hi,

I would like to install the docker version of phpDocumentor on my synology nas.

On terminal I tried:
docker run --rm -v /volume1/docker/phpDocumentor:/data phpdoc/phpdoc

Result:

Unable to find image 'phpdoc/phpdoc:latest' locally
latest: Pulling from phpdoc/phpdoc
bd159e379b3b: Pull complete
1e83b070fd97: Pull complete
e7793be89e9c: Pull complete
4220e0c03377: Pull complete
2eec08d1f85c: Pull complete
fad376bef81f: Pull complete
2eafa146ecd9: Pull complete
682415762cb7: Pull complete
bfac10460799: Pull complete
76d341c20979: Pull complete
dcef3ed72d52: Pull complete
34a69b8d93df: Pull complete
da1ea6b3d10a: Pull complete
Digest: sha256:69c786ec8238dc0e6adf3e6211eb82516cff339b064dfaaee79ed8824b01cb25
Status: Downloaded newer image for phpdoc/phpdoc:latest
phpDocumentor dev-master@144702e

Parsing files

Applying transformations (can take a while)

  1/21 [=>--------------------------]   4%
 11/21 [==============>-------------]  52%
 17/21 [======================>-----]  80%
 21/21 [============================] 100%
All done in 0 seconds!

Looks good. I see also file in my phpDocumentor folder.
But I see no phpdoc container and if I am using the command "phpdoc" in terminal:

-> phpdoc: command not found

Where is my mistake?

The raw directive stopped working starting with v3.2.0 and the contents of the raw code block is output as a regular escaped code block.

This is literally driving me crazy.

I do know PHP Documentor does some assumptions about _ underscores and basically things will/can go south when any variable, function name or even @Package tag has underscores in it.
I found solutions for all cases, but this one is ... just frustrating me.

1. Create a guide (not a PHP Doc block based documentation but a Guide) with .rst files
2. In a .rst file, add something like this:

Title Goes here
~~~~~~~~~~~

Some stuff here

3. parse that to a html guid
4. Works just fine, the resulting doc will have this HTML:

<div class="section" id="title-goes-here">
  <h2>Title Goes here</h2>
  <p>Some stuff here</p>
</div>

5. Repeat the same with a title that has underscores in it, like ... a function name my_cool_function()
6. Parse
7. Notice how PHPDocumentor stripped all _ out of the title
8. Workaround that by putting your title in either single or double back quotes
9. That avoids the underscores be stripped, but still, the HTML will be like so

<div class="section" id="30289u509823740589u289jwforijf9u3h298u24">
  <h2>my_cool_function()</h2>
  <p>Some stuff here</p>
</div>

Note how the ID became 30289u509823740589u289jwforijf9u3h298u24?
That will now also show as such in all TOCs.
Instead of my_cool_function() you will get 30289u509823740589u289jwforijf9u3h298u24 as anchor title in the TOCs.

I tried working around this by altering the TWIG templates, but as a matter of fact, that is not related to the TWIG template, it is related to something that messes with the _ in the parsing process. I am not sure what the purpose of this is, and how I can avoid it?
It does not generate beautiful content, and having random numbers (is it encoded somehow) in an URL is also not nice

Analysing this even further, I discovered that the encoded ID of the HTML happens only when you have backticks in the title.
But without backticks.... PHPDocumentor strips the underscores...

It would be great if I could link to local (e.g. Markdown) files, which would get included into the documentation.

For example inside package, classes and methods I could use something like

@link Documentation/Guide/How-to-use-lala.md Guide on using lala

I think I can remember that it was supported in phpDoc 1.x, but it seems to be gone in 2.x.

How are pages such as these created withing phpDocumentor?

https://docs.phpdoc.org/3.0/guide/getting-started/installing.html

Reading https://docs.phpdoc.org/3.0/guide/getting-started/generating-documentation.html

Expected behavior

Text should be:

After you have installed phpDocumentor

Actual behavior

Documentation source appears to cover for this with a custom link text

After you have :doc:`installed<installing>` phpDocumentor 

but for some reason this is not reflected in the generated documentation.

Steps to reproduce the problem

1. Go to https://docs.phpdoc.org/3.0/guide/getting-started/generating-documentation.html

Your environment

N/A

Feature request

Currently it is unable to exclude/ignore dot files and dot folders.
This is my configuration.

<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor
        configVersion="3"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="https://www.phpdoc.org"
>
    <title><![CDATA[RdbAdmin Module]]></title>
    <paths>
        <cache>.phpdoc/cache</cache>
        <output>.wiki/apidoc</output>
    </paths>
    <version number="latest">
        <api>
            <ignore>
                <path>.backup/**/*</path><!--not working-->
                <path>\.backup/**/*</path><!--not working-->
                <path>assets/**/*</path>
                <path>assets-src/**/*</path>
                <path>config/**/*</path>
                <path>languages/**/*</path>
                <path>node_modules/**/*</path>
                <path>node_tasks/**/*</path>
                <path>phinxdb/**/*</path>
                <path>Tests/**/*</path>
            </ignore>
        </api>
    </version>
</phpdocumentor>

I would like phpdocumentor to exclude everything in folder that start with dot. For example .backup, .dist, .vscode but it is unable to do that.
In version 2 I'm able to do that with this config.

files>
    <directory>.</directory>
    <ignore>.*/*</ignore>
    <ignore>assets*/*</ignore>
    <ignore>config/*</ignore>
    <ignore>languages/*</ignore>
    <ignore>node_modules/*</ignore>
    <ignore>node_tasks/*</ignore>
    <ignore>phinxdb/*</ignore>
    <ignore>Tests/</ignore>
    <ignore>Tests/*</ignore>
  </files

"Deprecated" originally meant "not recommended" in standard English, but, as phpDoc's docs itself explains, has come to mean in tech, "slated for removal", so we can't use @deprecated to mean only the former and not the latter.

It would be useful to have a standard that IDEs could recognize (and maybe specially highlight) that means "use this with caution / make sure you want to use/do this." I've seen IDEs, for example, employ this with SQL SETs without conditions, but those are hard-coded inspections, not generated from phpDoc.