Phpdocumentor: Documentation is abysmal

[joshmbg]

I'm trying really hard to figure out how to use phpdoc, but it's difficult because the documentation on docs.phpdoc.org is awful - it only covers a tiny fraction of the available options, it's really hard to find anything in it, and some of the links don't even work!

For instance, I'm trying to figure out what templates are. Currently I have no idea, because the templates link in the docs gives a 404 error. I eventually managed to find a page at https://www.phpdoc.org/templates, which appears to be a carousel of screenshorts, so I'm guessing that templates have to do with styling the output? I don't know. How do I use them? What do they do? Can I add my own?

I wasted a half hour trying to figure out why I was getting a screen full of error messages when I tried to run it, before I discovered that I was using parse instead of run, and failing to set a target directory (which appears to be mandatory, even though nothing tells me that).

I'm getting really frustrated, and the only reason I haven't given up on it completely, is that the only alternative I've been able to find is doxygen, which is even more complicated to use than phpdoc.

It's a really poor showing, when a documentation tool has such bad documentation.

I'm sure this is a great tool for the 115 people who know how it works internally, but for everyone else? We need better instructions.

[nelson6e65]

Yes. You are right. Documentation is in fractions and incomplete. And some parts are 404 or hard to find.

But I hope with the release of new version 3 the documentation becomes more friendly, using VuePress for example, which provides an easy and pretty way to create documentation and find topics. And, especially, using markdown syntax we all know which help us to contribute and improve it.

[jaapio]

Hi @joshmbg,

I'm sorry to hear your bad experience with phpdocumentor. We know that our documentation has some missing parts. And it can be very hard to get started with phpdocumentor.
The good news is that we are working hard to get our documentation up to date and more complete. One of the steps is that we are working on a new website which should collect all parts of the documentation.
Al this takes a lot of time. And since we are a very small team, progress is very slow. I could only dream of a team of 115 people who are contributing.

About your questions, phpdocumentor is using templates to format the output of the generated documentation. It is possible to write your own templates but since it is kind of hard to do without knowledge of the internals I would not recommend doing it.

The commandline interface is a bit cryptic in it's use. We want to improve the feedback during errors in a newer version of phpdoc. Which will be v3. Since the internals of phpdoc were based on php 5.3, we have a lot of work to do to keep up with the fast release schedule of php 7.

To get started it is most straight forward to have a look at the config of phpdocumentor itself.

<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor>
    <parser>
        <default-package-name>phpDocumentor</default-package-name>
        <target>build/api-cache</target>
    </parser>
    <transformer>
        <target>build/api</target>
    </transformer>
    <files>
        <directory>.</directory>
        <ignore>tests/*</ignore>
        <ignore>build/*</ignore>
        <ignore>var/*</ignore>
        <ignore>vendor/*</ignore>
    </files>
    <plugins>
        <plugin path="Core" />
    </plugins>
    <transformations>
        <template name="clean" />
    </transformations>
</phpdocumentor>

Most important sections are files and transformations you might want to extend the list of directories that is processed and choose a different template in the transformations section. You can use one or more templates. But in most cases a single template should be sufficient.

If you have any questions please don't hesitate to ask questions here on github. This will help us to get clear which parts of the documentation have to be improved. And how we should explain things in a more understandable way.

Thanks a lot for taking your time to contribute to phpdocumentor by asking questions!

[yojance]

Where is V3 being developed? Is there a road-map or release date anywhere?

[mvriel]

phpDocumentor v3 is developed on the develop branch. Unfortunately, progress is slower than we would like to see, but this is partly because we are only a small team and personal lives are also taking up time. As such we are unable to provide a release date at this point in time.

You can also track the project boards, these contain the latest state

[mvriel]

I am leaving this issue open for now as we acknowledge that the documentation can surely need some love and the suggestions made here help to improve this