Argh, phpDocumentor 3!

Arantor

So I have a hobby project and I'm trying to be conscientious and docblock everything. There's a lot of legacy cruft in there too.

At some point in the mists of time I set up a VPS and one of the things it did was grab the code once a day, run phpDocumentor on it and spit out all the class docs as nicely formatted HTML pages, including a report of all the things I still had to do. And since it was a few years ago, it was on a phpDocumentor 2.x build.

So far, so good, but it's been a few years, the project is looking at newer PHP versions and that meant it was time to move to phpDocumentor 3. Fiiiiiiiiine. I figured I'd also move the build process so that instead of running a build daily (when merges aren't daily), I'd tag it off a GitHub action to build the docs on merge to main branch and shunt the whole thing as static files to S3 and serve it that way.

The old theme it used to make files was classic, based on Bootstrap 2, and was alright. It wasn't fancy and at some point I'd make a new theme when I'd finished the bulk of other development or when I was bored.

The new version, though... fucking hell. The documentation has never been good for phpDocumentor but the current docs are the most awful fucking piece of shit I've ever seen for even a developer tool. Given that it includes such hilarities as suggesting reading the XSD schema for the XML configuration file actually in the manual page about the configuration file... fuck. The most amazing documentation about a configuration file I have ever seen. And this is utterly representative of the rest of the docs too.

But that I could live with. It was shit but I could live with it. Once it was set up I'd generally just leave it alone. Even the weird mostly undocumented change of globbing syntax was just annoying rather than a deal breaker - as in, I specify I want certain folders ignored. In 2.x config, this is <ignore>directoryName/*</ignore> while in 3.x this is apparently <ignore>directoryName/**/*</ignore> even though there is allegedly a compatibility shim to replace the former with the latter. My lived reality is that this is in fact a load of bollocks and that the only way it actually behaved was to <ignore>directoryName</ignore>. Which doesn't behave the way the manual (hah) suggests it should, or any of the comments in the GitHub issues tracker claim.

The kicker though was the error list. I needed that list of errors as a todo list. The old version of phpDocumentor raised 1440 errors in the codebase (which, at a glance, look legit). The new version running on the exact same repo returns a total of 9. Which is fuck all use to me. I know it's not excluding files, because it's spitting out references for them as it should, but if it doesn't report 'this class constructor doesn't have a docblock' it's no use to me.

The secondary hilarity about this is that it's not even that I'm missing configuration. I checked. The manual doesn't list what the configuration settings are but you can invoke a command line argument (that is only vaguely documented) to list what options exist that you can pass in and 'list missing docblocks as actual errors' isn't one of them. Nor is it reported on the command line while parsing despite claims that it would be.

Guess it's time to look at Doxygen instead, which is a shame because I've used phpDocumentor for years for this task and I liked how it worked but the 3.x release is a deal breaker.

toodle

Obligatory XKCD

Steve_The_Cynic

@Arantor Regarding awful configuration file documentation, take pity on someone trying to configure a GNU crontab in 1995 or 1996 (Slackware 3.1). man crontab gave me the most unedifying piece of information, that the format of the crontab is the same as for vixiecron.

Oh-Kay, but how about telling me about that format? Please? I've never used vixiecron.

Zecc

@Steve_The_Cynic I've never heard of vixiecron.

Sounds like something from the Romans or Greeks.

Copyright 1988,1990,1993,2021 by Paul Vixie

Gurth

Heh … now I was curious, so I did man crontab on my macOS 12:

DESCRIPTION
     The crontab utility is the program used to install, deinstall or list the
     tables used to drive the cron(8) daemon in Vixie Cron.

(…)

STANDARDS
     The crontab command conforms to IEEE Std 1003.2 (“POSIX.2”).  The new
     command syntax differs from previous versions of Vixie Cron, as well as
     from the classic SVR3 syntax.

AUTHORS
     Paul Vixie ⟨paul@vix.com⟩

macOS 12.0                      December 29, 1993                     macOS 12.0

Gąska

@Gurth said in Argh, phpDocumentor 3!:

AUTHORS
Paul Vixie ⟨paul@vix.com⟩

Good luck reaching anyone through that email. In other news, TIL about yet another streaming platform.

Arantor

arantor@apache:/var/www/html# man crontab
No manual entry for crontab

Well, that's fine...?

Steve_The_Cynic

@Gąska said in Argh, phpDocumentor 3!:

@Gurth said in Argh, phpDocumentor 3!:

AUTHORS
Paul Vixie ⟨paul@vix.com⟩

Good luck reaching anyone through that email. In other news, TIL about yet another streaming platform.

Probably worth trying vixie@isc.org as suggested by man 5 crontab in Fedora 14, where the format is fairly well-described, and no direct reference is made to vixie cron.

For what it's worth, the Unreliable Source says that Mr. Vixie is still with us(1), so in doubt, you could always try to ask him.

(1) I'm slightly surprised to see that he's only three years older than me, although that might merely indicate that I am an old fart.

Steve_The_Cynic

Hmm. Looks like I might have slightly derailed the thread. Enjoy.

Arantor

@Steve_The_Cynic YMBNH - de- is working as intended here.

Steve_The_Cynic

@Arantor said in Argh, phpDocumentor 3!:

@Steve_The_Cynic YMBNH - de- is working as intended here.

I know. That's why I invited y'all to "Enjoy" rather than apologising.

PleegWat

@Gąska said in Argh, phpDocumentor 3!:

@Gurth said in Argh, phpDocumentor 3!:

AUTHORS
Paul Vixie ⟨paul@vix.com⟩

Good luck reaching anyone through that email. In other news, TIL about yet another streaming platform.

I have heard of cases where a domain was sold under the condition that certain email addresses are forwarded in perpetuity.

toodle

@Steve_The_Cynic
Slackware 3.1 doesn't use GNU cron or Vixie cron.

As far as I can tell, Slackware has always (for some largish value of "always") used Dillon's cron.
Neither the Slackware 3.1 UPGRADE.TXT nor the ChangeLog.txt mention a move to
"Dillon's cron" from any other cron manager. As for the crontab(1) manpage, in 3.1 it included both
a crontab file layout description, and an annotated example of a valid crontab.

Perhaps you are thinking of some other distribution?

(edited to reflect found information about Slackware 3.1)

HardwareGeek

@Steve_The_Cynic said in Argh, phpDocumentor 3!:

I'm slightly surprised to see that he's only three years older than me, although that might merely indicate that I am an old fart.

He's a few years younger than me.

Steve_The_Cynic

@toodle said in Argh, phpDocumentor 3!:

@Steve_The_Cynic
I don't know about Slackware 3.1, but Slackware 3.3 doesn't use GNU cron or Vixie cron.
As far as I can tell, Slackware has always (for some largish value of "always") used Dillon's cron.
Neither the Slackware 3.3 UPGRADE.TXT nor the ChangeLog.txt mention a move to
"Dillon's cron" from any other cron manager, and the ChangeLog.txt goes all the way back to the
3.1.0 release. As for the crontab(1) manpage, in 3.3 it included both a crontab file layout description,
and an annotated example of a valid crontab.

Perhaps you are thinking of some other distribution?

No, it was definitely Slackware 3.1, although I might have been assuming things about that type of accessory.

It's still a godawful way of documenting the format of the crontab.

toodle

@Steve_The_Cynic
See my edits above. From the Slackware archives, you can still get the full
Slackware 3.1 install set, including manual pages and source code. The
source for the supplied cron is "Dillon's cron", and the crontab(1) manpage
definitely includes the layout and example crontab I mentioned.

Gurth

@Steve_The_Cynic said in Argh, phpDocumentor 3!:

Fedora 14, where the format is fairly well-described, and no direct reference is made to vixie cron.

I forgot to mention that it’s not described at all in the macOS manpage. That just gives the options for crontab itself without talking at all about how you would format the entries you may want to add — or even where you might find this information, making it even worse than @Arantor’s version that sparked this, IMHO. Even funnier is:

DIAGNOSTICS
     A fairly informative usage message appears if you run it with a bad command
     line.

OK, I’m game …

% crontab -q     
crontab: illegal option -- q
crontab: usage error: unrecognized option
usage: crontab [-u user] file
       crontab [-u user] { -e | -l | -r }

Steve_The_Cynic

@Gurth I had a similar problem on Fedora 14, which led me to man 5 crontab to look up the format of the file in section 5 of the manual (section 5 is file formats, while section 1, searched ahead of section 5 if you don't ask for a specific section, is for commands).

EDIT: and the error message is "fairly informative" (but only just): it tells you that it doesn't know what -q means, that it is going to fail because you asked it something it doesn't understand, and what the valid options are. It's not sufficiently informative, in that it doesn't even try to say what -e, -l and -r mean, nor what might happen if you specify a user with -u, but it at least gives a clue as to what might be wrong.

Steve_The_Cynic

@toodle said in Argh, phpDocumentor 3!:

@Steve_The_Cynic
See my edits above. From the Slackware archives, you can still get the full
Slackware 3.1 install set, including manual pages and source code. The
source for the supplied cron is "Dillon's cron", and the crontab(1) manpage
definitely includes the layout and example crontab I mentioned.

What about the crontab(5) man page?

Gurth

@Steve_The_Cynic said in Argh, phpDocumentor 3!:

@Gurth I had a similar problem on Fedora 14, which led me to man 5 crontab to look up the format of the file in section 5 of the manual

That gives useful information on macOS too (I just tried). It would help rather a lot if the crontab(1) page would refer to it, though.

EDIT: and the error message is "fairly informative" (but only just)

It is, but not as informative as the notice in the manpage makes it seem to be. I expected something more along the lines of a short explanation of the commands.

PleegWat

@Gurth said in Argh, phpDocumentor 3!:

It would help rather a lot if the man(1) page would refer to it, though.

I think you mean the crontab(1) page. The man(1) page may or may not explain what each section means, but I doubt you were looking at it.

Gurth

@PleegWat Yeah, that :) I confused the notation.

PleegWat

@Gurth There is also man -k, though in this case you wouldn't think of using that if you didn't already know there was a second page somewhere.

Steve_The_Cynic

@Gurth said in Argh, phpDocumentor 3!:

That gives useful information on macOS too (I just tried). It would help rather a lot if the crontab(1) page would refer to it, though.

Probably the cron(1) page does refer to it.

Checked: On Fedora 14, both cron(1) and crontab(1) have a "see also" that mentions crontab(5), although you do have to know what the numbers in the () mean...

Same thing on FreeBSD 13.0, whose userland is probably closer to MacOS's.

dkf

@Steve_The_Cynic said in Argh, phpDocumentor 3!:

although you do have to know what the numbers in the () mean...

The common notation for manpage crosslinks? You pick that up pretty rapidly once you start really using Unix documentation.

Steve_The_Cynic

@dkf said in Argh, phpDocumentor 3!:

@Steve_The_Cynic said in Argh, phpDocumentor 3!:

although you do have to know what the numbers in the () mean...

The common notation for manpage crosslinks? You pick that up pretty rapidly once you start really using Unix documentation.

Agreed, but you do have to pick it up. That's all I was saying.