This week I've got to keep it a little brief because I've been so caught up in this weeks' updates that I've run out of time to write much in this blog post! The updates this week are not actually to the core code, but rather to the API reference documentation for ProcessWire 3.x. There's lots more work to do still, but I definitely have a good start, so going to introduce it here in this post.
Introducing the ProcessWire 3.x API Reference Documentation
Here is the ProcessWire 3.x API reference documentation. Currently all of the API variables are covered, but the individual classes (like WireData, WireArray, etc.) and non-API variable modules have not yet been covered–that'll be next week.
Please take a look around, there's a lot of new stuff here. Not new stuff in terms of code or functionality, but rather new stuff in terms of documentation coverage. Many API methods include detailed code examples, comprehensive options lists, and more. Hookable methods also get their own section that shows you how to hook the method, what the arguments are that you can hook, and examples of how to do so.
Something unique about this API reference
I've always struggled a bit to keep our existing API reference documentation fully up-to-date with the actual code. It's a matter of time and resources. That will no longer be a problem. This API reference is actually powered by a module built this week (ProcessWireAPI) that pulls all the documentation directly from the core code itself. It does this using a combination of PHP's Reflection classes, manual parsing of phpdoc comments, custom hash tags, and example blocks that have been added to the core.
What this means is that the documentation will always be fully up-to-date with the core version that processwire.com is running on. Or if we wanted to have different versions of the documentation, we'd just let each version run off of different versions of the core. The entire API reference (hundreds to thousands of URLs) is powered by one single page in the system, and none of the documentation content is coming from content stored in ProcessWire–just in the actual PHP code of the core source.
It also means that the source code documentation in core files is going to be getting a lot more comprehensive, since it's now powering the actual API reference documentation. This week I've re-written huge amounts of the documentation present in the core source code, which you'll see committed to the devns branch next week. Though you'll see that already powering the 3.x API reference linked above.
What about the cheatsheet?
Part of the reason I wanted to get the API reference powered by a module, is so that there could be an API to the API. :) Meaning, we'll be able to use the ProcessWireAPI's module API to display API reference material in the cheatsheet. Though the cheatsheet already has a lot of good content, so we'll try to find a way to make sure that all the good features and content already in the cheatsheet remain, while taking advantage of the ProcessWireAPI module to ensure everything is always up-to-date. Basically, the cheatsheet is one of our most important resources, so all of this is kind of planned around that.
What else is coming for the API reference documentation?
Right now the API reference documentation focuses largely on the API variables. But there's a lot more to cover, especially in terms of other ProcessWire classes (like WireArray, WireData, and dozens of others). Technically, the API reference documentation can display information for any PW class already. But I'm trying to avoid linking to those classes until I've gone through and curated each one, like was done for the API variables this week.
By curating, I mean making sure the content is as high quality as it can be, as opposed to just being informal developer comments in the code. Curating also means figuring out what's important and what's not, and making sure that largely "internal" stuff doesn't get in the way of the more important stuff. It also means grouping things in a logical manner that make sense for documentation. Basically, it's a lot of work, but really worthwhile I think.
The API documentation obviously needs a bit more navigationally in terms of UI too, so that'll be coming as well. Though since we're going to get back to our redesign soon, we probably won't focus too much on look and feel of the API reference until we're in the process of the overall site redesign.
With this weeks' updates the intention is to bring our API documentation up to the level of the API that it covers. Next week I hope to finish re-writing documentation for most of the remaining classes. Hope that you all have a great weekend and see you at the ProcessWire Weekly!
Comments
SiNNuT
- 9 years ago
- 20
★★★★★Awesome! Great projects deserve great docs. ????
Reply
ryan
Can, Teppo: @since support is already built-in, but I'm not outputting any @since tags yet because @since 3.0 is already the underlying assumption of the entire API documentation. The starting point in time for this documentation section is yesterday, and it's not going to be able to cover previous versions of PW until the current version is considered a previous version. Something you'll like: There's also a #pw-since hash tag supported that can be assigned to method arguments, return values, or even components of array based $option arguments. Once the first non-dev PW3 version is released, these new API docs will start displaying @since phpdocs (and #pw-since hash tags) whenever there is something new to document. I'm not currently planning on having these API docs cover v2.x versions of PW, which is what all the previous documentation prior to this has been covering, and will continue to do so (though will move to a dedicated 2.x section once 3.x is released). I'm thinking it will be possible for the cheatsheet to cover both 2.x and 3.x simultaneously though, as it already has all the 2.x content built-in, and it can pull 3.x content from the ProcessWireAPI module.
Reply
Grimezy
Great addition Ryan.
I always found myself browsing between the forums, the API cheetsheet and previous blog posts to find code examples. This now provides a fast way for beginners like myself to look for references and examples, which in turn, should neaten and provide higher quality questions and answers on the forums. Well done.
Reply
ryan
Thanks, fixed!
Reply
Can
- 9 years ago
- 40
★★★★★Awesome, what a great solution!
How about adding something like @since 3.0.15 to the phpdoc or wherever so when looking in the docs one will see what version he needs..
What do you think?
Reply
ryan
I don't know about style guides or pattern libraries, but the module itself will generate documentation for any PHP class–it doesn't really have anything to do with PW per-se, other than some custom "#pw-hash-tags" I've added to support things outside of what phpdoc supports. I can run it on ProDrafts for instance, and I get this: https://processwire.com/api/ref/drafts/ – keep in mind, the phpdoc it's pulling from is currently just "informal notes for the developer", as is the phpdoc in most classes. Nothing there has been organized or planned for this purpose yet in a module like that. But I'll no doubt be updating modules like that to have the same kind of curated documentation that the core will have, so that they can produce quality output for this. In addition to providing an API to documentation of PHP classes, the ProcessWireAPI module is actually a Process module that produces an "API Explorer" page in the admin with the same output you see here, so maybe a good one to release at some point.
Reply
Teppo
- 9 years ago
- 11
★★★★★Definitely agree with what Can said above.
On a typical day at the office I work with ProcessWire versions ranging from 2.2 to 3.x and my mental capacity is not nearly enough to remember which feature was added at what point and whether (and how) the behaviour of API variables, core classes, etc. differs between specific versions.
It would be tremendously useful to have the documentation figure it out for me, preferably so that I can filter results based on the version I'm currently working with. Displaying @since in the context of a specific API var or core class would be useful for other reasons too (not to mention a changelog in case things have changed since the feature was first implemented).
Reply
Tom
- 9 years ago
- 40
★★★★★Awesome work Ryan! Such an elegant solution. This is what makes ProcessWire so great. You see a problem and always give thought for the best solution, rather than the first solution most people would think of. (Manually writing all the documentation). Love the creative thinking Ryan!
Reply
Nico
Awesome solution!
Reply
blynx
- 9 years ago
- 10
★★★★★So nice!
So, basically we can also add documentation suggestions per github then - a bit wiki-like -
A little bug I found:
When clicking on a link on https://processwire.com/api/ref without a trailing slash it leads me to e.g. https://processwire.com/api/database/ instead of https://processwire.com/api/ref/database/ ...
Reply
Michael Murphy
- 9 years ago
- 10
★★★★★Could this new approach and functionality be used to auto generate things like project style guides, pattern libraries and documentation in our own projects?
Reply
nfil
- 9 years ago
- 00
★★★★★Thanks Ryan.
Reply