Current API docs do not match current release

[jnardiello]

Current API documentation describes version 3.7.3.

> 4.x brought major changes in classes behaviours and signatures. Until new api docs are released, there should be at least a warning for users.

[mtdowling]

Yeah, I haven't been updating them because I personally don't find API docs that useful and haven't received any requests before this one for Guzzle 4. Bringing API doc generation back into the Guzzle release process will actually require a release process. Right now I just need to push a tag and I'm done. In order to bring back doc generation, I'd want to setup a server to poll for tags and automatically generate and deploys docs when a release goes out. I'm not sure if such a tool already exists (other than setting up a Jenkins box with custom build trigger scripts).

[GrahamCampbell]

Sami is able to generate docs for git tabs together.

[mtdowling]

I'm not worried about being able to generate for multiple versions (mostly cause I wouldn't do that and would only have the latest version). I'd also never use Sami for API docs as it isn't maintained and lacks a ton of features (I know because I submitted PRs years ago that were never looked at).

[jnardiello]

Code and test are simple and clear enough to actually document how Classes
work. Still, i find very confusing having the main project page describing
Guzzle 4.x, while on the same website APIs are completely outdated. I agree
that generating docs is really time-consuming and we can easily decide to
skip them, still it should be stated somewhere on API pages that they are
referring to 3.x.

Anyone working with Guzzle from time to time (but not on a daily basis)
will have a hard time figuring this out -as it happened to me this morning.
Is there a way i can fix this with a PR?

On Mon, Jul 28, 2014 at 9:38 PM, Michael Dowling notifications@github.com
wrote:

I'm not worried about being able to generate for multiple versions (mostly
cause I wouldn't do that and would only have the latest version). I'd also
never use Sami for API docs as it isn't maintained and lacks a ton of
features (I know because I submitted PRs years ago that were never looked
at).

—
Reply to this email directly or view it on GitHub
#750 (comment).

• J

[nurikabe]

+1

Just ran afoul of this myself.

[beefsack]

Just spent a couple of hours being confused by the API docs then, would be good to have a message on the docs relating to which version they are relevant for.

[atrauzzi]

👍

Same here. Still trying to figure things out, and feeling a bit mislead.

[benjaminkohl]

I'm always struggling to find the correct docs for the version we are using. I just realized that the tagging system changed to drop the "v" which is why I never even knew where 4.0.* was coming from. I was under the impression that v3.8.1 was the latest until I scrolled down to see the 4.0.* and 5.0.* releases.

[brettlangdon]

mtdowling you can always host static docs on github pages, which is similar to pushing a tag (gen docs and push to a branch) or you can use readthedocs which uses python/sphinx/rest to generate the docs.

[mtdowling]

The user-guide for Guzzle is already on rtd, but Sphinx doesn't support automatically documenting PHP projects.

Yeah, GitHub pages would work. I'd like to see if I can use that or S3 to automatically build and publish the docs when a tag is pushed. This can be done through Travis CI with http://docs.travis-ci.com/user/deployment/. See also http://mtdowling.com/blog/2014/10/26/managing-changelogs-with-chag/

[brettlangdon]

ah, yeah... autodoc doesn't really work with php.

neat, +1 for travis s3/github pages.

[Erutan409]

Forgive me for chiming in, but this seems like somewhat of a turnoff if I'm to believe any documentation isn't relevant/correct for the current release of guzzle. I've been contemplating replacing my custom-written cURL library with guzzle after seeing it being used in conjunction with elasticsearch php library.

Will it be a bumpy road ahead of me trying to adopt this library?

[GrahamCampbell]

I think you should just delete the API docs @mtdowling.

[jnardiello]

I think he should just put a disclaimer somewhere making clear that they are not addressing the current stable release.

[mtdowling]

Yeah I'll delete them

On Jun 4, 2015, at 4:35 PM, Graham Campbell notifications@github.com wrote:

I think you should just delete the API docs @mtdowling.

—
Reply to this email directly or view it on GitHub.

[mtdowling]

The old docs will be deleted within the next 24 hours.

[adamcameron]

Sorry to drag up an old ticket. Just fell foul of this and sank a lot of time googling for the API docs because it would never ever occur to me that an API would not have them. So just presumed I couldn't find them.

I dunno how often the API changes (ideally not very often!)... would it not be viable to generate them manually once and generate mark-down files and just save 'em here. Then as bits 'n' pieces of the API change, then just keep the docs up-to-date manually? At the very least ppl who find out-of-date parts of said docs could pitch in and fix 'em.

If it was down to me, I'd probably eschew all the rest of the docs, and just have API Docs. That'd be the baseline starting point. Not to be contrary but just to show "I personally don't find API docs that useful" is perhaps not the only viewpoint to consider when exposing a project to the gen. pop.

Anyway, just and idea and an observation, and I don't mean to be volunteering anyone for work they don't feel like doing.

Cheers for the otherwise excellent project!

[Arteneko]

I feel the same.

I've been searching for Guzzle API docs and the only answer I found was this SO thread whose comment "What a joke, API docs are exactly what I need right now." is the exact feeling I'm having.

API docs are very useful, maybe even more than handwritten walkthrough docs, as they can answer very technical details that could, for example, lead to easier debug and fixes.

If the sourcecode is PHPDoc'd (haven't checked rn), I may take some time working on automated doc generation but I feel it is an important work, as it also helps better coverage and API docs are a form of specification.

[rmccullagh]

Without API docs, the guzzle library is a black box. Okay, so what is the return value of getStatusCode (int, string, some type of enum, etc)? Don't know.

[stefanfisk]

For someone with as fucked an attention span as me (ADHD sucks 😿), not having a clear API reference to search means I lose track of what I'm doing again and again because I have to spend so much time and mental effort on scanning the walkthrough style docs for whatever detail I need.

Currently my solution is to open the relevant Guzzle source file a browser or editor, but that's nowhere near as readable as even the most basic phpdoc HTML export.

[WilliamVenner]

It's simply nonsense for such a popular project to have no API docs, especially when everything is already PHPDoc'd (at least to a basic extent.) Unfortunately my experience in making middleware has been a pain without them.