Is this the right tool for public API documentation?

theseer / phpdox

Documentation generator for PHP Code using standard technology (SRC, DOCBLOCK, XML and XSLT)

http://phpdox.de

Other

600 stars 121 forks source link

Is this the right tool for public API documentation? #371

Closed claytron5000 closed 4 years ago

claytron5000 commented 4 years ago

I want to use a php documentation generator to document a public facing API. phpDox works great, but it appears it doesn't get very granular in how much masking/showing it is able to do, at least not without some heavy xml template editing.

Basically my use case is:

run the generator in a particular directory
manually limit the classes shown (incomplete/broken endpoints)
show only select parts of the classes: docblocs, method names, no source code.

Is this possible/easy in phpDox?

theseer commented 4 years ago

I'm not sure I understand your requirements correctly: Does public API mean callable via - for instance - HTTP? Of so, then phpDox is certainly not for you.

If you aim to provide documentation on your library for others to use, maybe. PhpDox has not been designed with that use case in mind but you can make it probably work.

The idea behind phpDox is to generate code level documentation enriched with results/reports from various external tools. And I certainly have to add a bunch of new enrichers to cover all the new tools that came up since phpDox' invention.

That being said, you can tell phpDox to only render public methods of classes and you can specify - in what I believe to be quite sophisticated ways - what files to have included and excluded based on pattern matching rules (like shell wildcards, ...) for instance.

TL;DR: If in doubt, the answer is probably no.

claytron5000 commented 4 years ago

I don't mean publicly callable, though that'd be amazing.

What I don't really want to do is to expose possibly buggy/insecure code to our API consumers. The publiconly="true" attribute goes part way, but the source code is still exposed. Do you recommend editing the templates to exclude source code? That's sort of where I've started, but I'm not sure if I'm opening a can of worms.

btw, bonus points for replies in < 3 minutes, wow!

theseer commented 4 years ago

There is currently no option to hide the source code.

If you'd like to add that as a switch into a PR, I'd be happy to add this feature. It should be quite easy to not generate source code in html - it's basically disabling one call for each class file.

It's a bit harder to not have links in the other parts of the output though. I'd have to look into that but won't have much of a chance before mid october I'm afraid...

theseer commented 4 years ago

You can of course always create your own engine (= output generator). It's rather straight forward: phpDox will call your engine code for "event" type you register for (see the html engine for instance).

claytron5000 commented 4 years ago

Thanks @theseer, I'll talk to the team tomorrow about how we're going to move forward. If we move forward with option 1 I'll make a PR.