WooCommerce Code Reference

[santanamic]

I noticed changes in the documentation. This is horrible compared to before. Woocommerce had the best documentation for an open source project. Now everything is an unproductive mess.

[peterfabian]

Hi, thanks for the feedback! Can you please be more specific about what you don't like about the new documentation?
Unfortunately, the previous one we had hasn't been updated for quite some time, so we started using a new PHPDoc tool, but maybe we can make it useful to you again?

[starypop]

Hi @peterfabian!

I've got some improvement/fix ideas:

1. Restore a way to browse the source code of methods and clasess. In the previous version it was possible by clicking the name of the file that contains a method. Now I cannot find it, so the whole code reference is kinda useless for me.
2. Remove underline from links in the first column with method names, because there's no way to see the underscores.
3. Do not wrap method names in that column, or at least do not wrap it in the middle of a word.
4. Make the first column a lot wider. Now the last column with parameters description is to wide. And use smaller line-height than in the description column.

Here's a screenshot showing current columns:

[starypop]

It would be also nice to display WC version since a method has been deprecated.

Eg. https://woocommerce.github.io/code-reference/classes/WC-Abstract-Legacy-Order.html#method_get_product_from_item

[gregs-legs]

I entirely agree. It is unreadable. Moreover the links to the source code simply redirect you to more documentation. You go around in circles but never actually get to the code. A big step backwards.

[santanamic]

I agree with @starypop # 1. There is a lack of direct visualization for implementing class / methods/ functions/ templates.

Another thing is that woocommerce.js has some useful events however in the documentation they are not mentioned.

[peterfabian]

Bumping the priority as for an open source project, having a usable and good documentation is important.

[claudiosanches]

There's already a repository for it, we should move all issues related to the code reference to it's repository.
I'm going to move this issue there.

@starypop please feel free to open issues on https://github.com/woocommerce/code-reference
Thanks for your suggestions.

[claudiosanches]

@gregs-legs @starypop note that we had to move from APIGen to PHPDoc 3 RC, also APIGen stayed deprecated for almost 3 years, there's almost 2 years that we haven't updated our code reference, so all results for before was outdated, comparing both frameworks for sure there's things that we'll miss now, but we can't go backwards to APIGen again, but I'll appreciate all your help, since the code is open source and you'll can contribute in here. Thanks!

[claudiosanches]

Restore a way to browse the source code of methods and clasess. In the previous version it was possible by clicking the name of the file that contains a method. Now I cannot find it, so the whole code reference is kinda useless for me.

We can't restore it, since we are using a new framework, we could try to work in some alternative.

[claudiosanches]

Do not wrap method names in that column, or at least do not wrap it in the middle of a word.

This not will not be possible, not without sacrificing to be mobile friendly.

[claudiosanches]

@santanamic

Another thing is that woocommerce.js has some useful events however in the documentation they are not mentioned.

We never had any reference for woocommerce.js in our previous code reference. This one doesn't sounds related to this issue.

[claudiosanches]

@santanamic

I noticed changes in the documentation. This is horrible compared to before. Woocommerce had the best documentation for an open source project. Now everything is an unproductive mess.

Can you please list everything that you believe is unproductive?
You can open an issue for each item, so we can discuss each one.

[gregs-legs]

The documentation used to be really useful to understand the class hierarchy, for moving between classes, finding the function and then linking to the code.

As it stands the functions list is unreadable - why give it such a narrow column ? Mobile Friendly ? Really ? How many people code on a mobile phone ?

If you can find the function you are looking for, it helpfully (??) tells you where the function is - php file name and line number. But the link no longer takes you to that file and line, rather it takes you to another class reference file. You just go round in circles.

What was good resource has been rendered pointless.

[claudiosanches]

@gregs-legs @starypop I just submitted a sample of the new template I'm working on, you can check it on: https://woocommerce.github.io/code-reference/v2/ (please note that the search is not set to work in that sub directory, but everything else should work).
Please let me know how it feels now. Thanks!

[gregs-legs]

Disappointed to see this marked as closed - you've addresed some styling issues but a pointless document that looks nice is still pointless.

By merging all class functions and inheritted class functions in to one page (plus an slightly expanded version of the same information lower down the same page) you can't see the wood for the trees. The old reference document used to be really useful for undertanding the scope of a class and seeing where it sits in the hierarchy.

With this new reference document - you have to scroll through pages and pages of functions from other classes in the hope of finding something useful from the class itself. You really don't get any feel for what the class is all about or where it sits in the hierarchy. Moreover, you inevitably resort to a digital search and hope you've guess the key word correctly. But of course, if you already know what your looking for you might as well search the code itself. So what's the point of the reference document ?

When it comes to a reference document - less is more. A simple list of member data and functions within the class and a separate list of inheritted functions is all that is required. With a direct link from each function to the code. Simple and useful.

[claudiosanches]

@gregs-legs sorry, but I addressed all issues listed in here. If I missed something I'm sorry. If you like we can start a new issue and we could work on those. So please don't be disappointed, I'm trying my best here, no feedback aren't getting ignored.

Can you please elaborate what was better from the previous framework that's not so great on PHPDoc?
Because for me I had several problems to find functions and other resources using the old code reference with ApiGen.

With this new reference document - you have to scroll through pages and pages of functions from other classes in the hope of finding something useful from the class itself. You really don't get any feel for what the class is all about or where it sits in the hierarchy. Moreover, you inevitably resort to a digital search and hope you've guess the key word correctly. But of course, if you already know what your looking for you might as well search the code itself. So what's the point of the reference document ?

This is an screenshot from the previous page:

Starts with a Packages summary that was always broken, after there's a "Classes summary" listing all classes, after all the classes there's a list of interfaces, exceptions and functions.
And in the sidebar a list of Packages (note that we increased the number of packages since WooCommerce 3.6, the last time we could make ApiGen work), and after starts a list of all the classes, in the bottom you can also find Interfaces, Exceptions and "Functions" that only list the WC() function, nothing more.

You can check the footer in here:

So as you can see, all results get duplicated from the first page and the menu, there's also missing functions and no support for namespaces, something that we started to use and we should replace the use of Package in new code.

Other thing that got improve in the new documentation is that now we can search for hooks and all items will redirect you to the source code in the code reference, and there's no more links to GitHub as used to be in the old documentation.

When it comes to a reference document - less is more. A simple list of member data and functions within the class and a separate list of inheritted functions is all that is required. With a direct link from each function to the code. Simple and useful.

Please tell exactly what you don't think that plays well in the current front-page, maybe I can try to move into some sub-page.

[claudiosanches]

By merging all class functions and inheritted class functions in to one page (plus an slightly expanded version of the same information lower down the same page) you can't see the wood for the trees. The old reference document used to be really useful for undertanding the scope of a class and seeing where it sits in the hierarchy.

Note that this is a default on PHPDoc, I'm fixing several bugs on PHPDoc that isn't even fixed on their side, so I'm really trying my best in here. So please let's talk, I'm only trying to help everyone in here.

[claudiosanches]

Ohh, I think I found what you are talking about:

Are those sections Direct known implementers and Indirect known implementers is what you are missing?
If so I can try to extend PHPDoc to include those, please let me know what else we could do.

[claudiosanches]

Closing in favor of #11