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!