Title: Better WordPress Code Reference Author: Siobhan Published: March 7, 2013 Last modified: May 14, 2015 --- [ ](https://profiles.wordpress.org/siobhan/) [Siobhan](https://profiles.wordpress.org/siobhan/) 6:50 pm _on_ March 7, 2013 Tags: [devhub ( 37 )](https://make.wordpress.org/docs/tag/devhub/) # Better WordPress Code Reference Discussions have been ongoing about better code reference for WordPress. Here’s where we are so far: * [@rmccue](https://profiles.wordpress.org/rmccue/), [@duck_](https://profiles.wordpress.org/duck_/), and [@djpaul](https://profiles.wordpress.org/djpaul/) have been [developing the parser](https://github.com/rmccue/WP-Parser), which isn’t far off * we need to have a discussion about how be are going to do user contributions. Are we going to use WP comments functionality? I thought it would be cool if we attach a taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. [https://codex.wordpress.org/Taxonomies#Default_Taxonomies](https://codex.wordpress.org/Taxonomies#Default_Taxonomies). to the comments we could tag them as explanation or example and they could be spat out in the right place. This would require a Code Reference Moderator, so someone would need to take on that role (and get all of the glory that entails) * We have three wireframes which [@melchoyce](https://profiles.wordpress.org/melchoyce/) is going to turn into a design. We will need designs for the following pages: * landing page * individual function page * archive page We also may need: * standard narrative page * APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. pages (though [@nacin](https://profiles.wordpress.org/nacin/) suggested that these would live in the PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. Dev Handbook) Here are the wireframes thus far: Landing Page [⌊Landing Page⌉](https://make.wordpress.org/docs/files/2013/02/Landing-Page.png) Function Page [⌊FunctionPage⌉⌊FunctionPage⌉[ Archive Page [⌊archive_page⌉⌊archive_page⌉[ Please feel free to comment on these, however please focus on the following questions: * are there any navigation elements you feel are missing from the landing page? * are there any other developer resources you feel should be featured on the landing page? * are there any navigational elements missing from the individual function page? * are there any content elements missing from the function page? * would it be useful to have a page that lists every function, like: https://codex. wordpress.org/Function_Reference? * as a developer, are their any elements of a code reference that you would love to see included but that we haven’t allowed for yet? [#devhub](https://make.wordpress.org/docs/tag/devhub/) ### Share this: * [ Threads ](https://make.wordpress.org/docs/2013/03/07/better-wordpress-code-reference/?share=threads) * [ Mastodon ](https://make.wordpress.org/docs/2013/03/07/better-wordpress-code-reference/?share=mastodon) * [ Bluesky ](https://make.wordpress.org/docs/2013/03/07/better-wordpress-code-reference/?share=bluesky) * [ X ](https://make.wordpress.org/docs/2013/03/07/better-wordpress-code-reference/?share=x) * [ Facebook ](https://make.wordpress.org/docs/2013/03/07/better-wordpress-code-reference/?share=facebook) * [ LinkedIn ](https://make.wordpress.org/docs/2013/03/07/better-wordpress-code-reference/?share=linkedin) * [Login to Reply](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fdocs%2F2013%2F03%2F07%2Fbetter-wordpress-code-reference%2F%23respond&locale=en_US) 1. ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) 2. [Siobhan](https://profiles.wordpress.org/siobhan/) 6:51 pm _on_ March 7, 2013 3. btw, I’ve already noticed that a narrative explanation area is missing from the function page. 4. ![](https://secure.gravatar.com/avatar/615b44e0863a83d3276cccf3661877715721fe88acc4dd4048f76f89caccc52f? s=32&d=mm&r=g) 5. [BFTrick](https://profiles.wordpress.org/bftrick/) 7:05 pm _on_ March 7, 2013 6. I think the wireframes look great! 🙂 7. For the user submitted examples on the 2nd wireframe how would those be ordered? Chronologically? Would there be a way to upvote or downvote examples so that the best ones float to the top? 8. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 7:19 pm _on_ March 7, 2013 * I’m not averse to upvoting and downvoting, although I’m keen to make sure we have quality control so curation will be an important aspect to it. * I’ve no idea what the development would be like on a voting system. - ![](https://secure.gravatar.com/avatar/8e4ce80a4094e63e2966ef5eb11982baba5aa128b22c3c88df5a71be71112dec? s=32&d=mm&r=g) - [@modemlooper](https://profiles.wordpress.org/modemlooper/) 7:20 pm _on_ March 7, 2013 - You will get trolls if it’s not moderated. 9. ![](https://secure.gravatar.com/avatar/8e4ce80a4094e63e2966ef5eb11982baba5aa128b22c3c88df5a71be71112dec? s=32&d=mm&r=g) 10. [@modemlooper](https://profiles.wordpress.org/modemlooper/) 7:10 pm _on_ March 7, 2013 11. Lurking, wish these changes were happening on bp.org. 12. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 7:21 pm _on_ March 7, 2013 * Can’t you use all of the work for bp.org as well? - ![](https://secure.gravatar.com/avatar/8e4ce80a4094e63e2966ef5eb11982baba5aa128b22c3c88df5a71be71112dec? s=32&d=mm&r=g) - [@modemlooper](https://profiles.wordpress.org/modemlooper/) 7:25 pm _on_ March 7, 2013 - I don’t know, John has the whole codex locked down and whenever things are discussed it never gets finished. - I guess the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. team is too busy and nobody wants to delegate responsibility. I’m for replicating what enhancements are being made here. * ![](https://secure.gravatar.com/avatar/496b8d78333d03512679c1c1d343cb82f563f5beb4d0f6f9368c0c95b95ed3cc? s=32&d=mm&r=g) * [Paul Gibbs](https://profiles.wordpress.org/djpaul/) 7:47 pm _on_ March 7, 2013 * Ye of little faith. - ![](https://secure.gravatar.com/avatar/8e4ce80a4094e63e2966ef5eb11982baba5aa128b22c3c88df5a71be71112dec? s=32&d=mm&r=g) - [@modemlooper](https://profiles.wordpress.org/modemlooper/) 12:50 am _on_ March 8, 2013 - ha! 13. ![](https://secure.gravatar.com/avatar/a2293936b68aa6f07397754f9d1ae2b771b12ad56f868a980206b8d96f1bad31? s=32&d=mm&r=g) 14. [Michael Fields](https://profiles.wordpress.org/mfields/) 7:45 pm _on_ March 7, 2013 15. This is going to be very awesome! Here is some feedback based on the questions you asked: 16. > Are there any navigational elements missing from the individual function page? 17. I see links for Classes, HooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., and Functions on the landing page but do not see these on the function pages. 18. > Are there any content elements missing from the function page? 19. The example does not use a deprecated function. What would one of these function pages look like? Would they still have the full source and “Use” sections? Should they include the “Add Example” form at the bottom? 20. > Would it be useful to have a page that lists every function, like: [https://codex.wordpress.org/Function_Reference](https://codex.wordpress.org/Function_Reference) 21. I think something like this would be useful to newer developers. When I first started really digging into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. I used phpxref and the most useful page was the one that listed all of the functions. I would go to this page all of the time and do an in-page search for the full function name and be able to find what I was looking for with ease. In cases where I may not know what I needed I could search for a key word, like “categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging.”, and find all function with this term in their names. I realize that most of the functionality that I describe seems to be provided by the search function on the homepage especially if it includes search suggestions. What the search does not provide though is the ability to open each function name in a tab. 22. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 8:34 pm _on_ March 7, 2013 * Thanks for the really useful feedback. * Class, HooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., & Functions on function page – we discussed having a short sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. navigation so these could go there. Anything else that would be useful in a sidebar nav? Maybe something like related functions? * Deprecated function: great point. I’m really not sure what to do about this. Do developers still need the information for reference? We should definitely close comments on deprecated functions. * List page: it sounds to me that what you actually want is the ability to open the function name in a new tab. Is it possible to build that into the search box? Like an Open Here | Open in New Tab link? - ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) - [Siobhan](https://profiles.wordpress.org/siobhan/) 8:35 pm _on_ March 7, 2013 - @rmccue – can you update the function page with a right hand sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme.? - Also, feel like knocking up a deprecated function page? * ![](https://secure.gravatar.com/avatar/689ddc4f33541ac4a001d247e560f8805d219a95e7e42a16e0d22b9409f385cb? s=32&d=mm&r=g) * [Andrey "Rarst" Savchenko](https://profiles.wordpress.org/rarst/) 9: 15 pm _on_ March 7, 2013 * QP simply does big red warning for deprecated functions, ex [favorite_actions()](http://queryposts.com/function/favorite_actions/). It’s not practically different to have special page for them or something. - ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) - [Siobhan](https://profiles.wordpress.org/siobhan/) 8:46 am _on_ March 8, 2013 - That’s a good idea. Maybe we could have a tickbox in the back end that marked it as deprecated. It could do the following: * add a big red warning * turn off comments - ![](https://secure.gravatar.com/avatar/689ddc4f33541ac4a001d247e560f8805d219a95e7e42a16e0d22b9409f385cb? s=32&d=mm&r=g) - [Andrey "Rarst" Savchenko](https://profiles.wordpress.org/rarst/) 9:11 pm _on_ March 8, 2013 - Note that deprecated things are marked as such in source, so there is no need for manual control – it is simply parsed and used. 23. ![](https://secure.gravatar.com/avatar/8214ad4fd18ee393ae0681f7ac3dce4361ffcb790ae1d6f262a5407101570429? s=32&d=mm&r=g) 24. [Dave Clements](http://www.davidclements.me) 8:01 pm _on_ March 7, 2013 25. Great start. Would be great if each function had a better description of the arguments that each function accepts, and in what format. 26. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 8:46 pm _on_ March 7, 2013 * I’ll let @rmccue take this one. I think this will largely depend on what’s available in the docblock. - ![](https://secure.gravatar.com/avatar/689ddc4f33541ac4a001d247e560f8805d219a95e7e42a16e0d22b9409f385cb? s=32&d=mm&r=g) - [Andrey "Rarst" Savchenko](https://profiles.wordpress.org/rarst/) 9:19 pm _on_ March 7, 2013 - Yep, from my experience code alone does not provide useful enough argument data. This largely depends on quality of available PHPDoc (which btw also related to IDE development experience and some related quirks in WP’s PHPDoc can be outright maddening 🙂 * ![](https://secure.gravatar.com/avatar/496b8d78333d03512679c1c1d343cb82f563f5beb4d0f6f9368c0c95b95ed3cc? s=32&d=mm&r=g) * [Paul Gibbs](https://profiles.wordpress.org/djpaul/) 11:06 pm _on_ March 7, 2013 * It is/should/will be possible, and is important to include. * I consider the Source section to not add much value, especially if you link to the tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.[https://core.trac.wordpress.org/](https://core.trac.wordpress.org/). browse URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org for each function. 27. ![](https://secure.gravatar.com/avatar/35f5693da773a4ec35124e9a69fcb980b27274de49d6acc406f9d29c93e5fd7b? s=32&d=mm&r=g) 28. diggy 8:09 pm _on_ March 7, 2013 29. I’d leave out the contributor credits, it’ll only clutter the page with irrelevant info. Or maybe only show it on hover. Also, one is clearly invited to add examples, but how to actually edit the page or view the history? 30. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 8:43 pm _on_ March 7, 2013 * Contributor credits are important as we really want to encourage people to contribute to docs. * The majority of the body of the page is generated automatically, the only thing we should need user input from is examples and explanations. * The challenge is going to be ensuring that all the docblocks have the necessary information, but we’ll cross that bridge when we come to it. * Version control is a broader issue. I think the current consensus is that we should wait until the revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. work for WordPress 3.6 is complete and see how we can make use of that. 31. ![](https://secure.gravatar.com/avatar/3c2d35c70cfeb674f1fddcff8fdc6010f63d833d4ead58bba947d7578f039bd3? s=32&d=mm&r=g) 32. [Stephen Cronin](https://profiles.wordpress.org/stephencronin/) 5:30 am _on_ March 8, 2013 33. One potential missing item is a place to link to an external resource. There are pages on the Codex where a link to a write up by Mark Jaquith or Otto has been of great benefit. Obviously these links could be a target for spammers, so would need some sort of control, but they would provide value. 34. Or would people be able to add links under the examples area? 35. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 8:46 am _on_ March 8, 2013 * Yrs, definitely needs to be added. Thanks for your input! 36. ![](https://secure.gravatar.com/avatar/496b8d78333d03512679c1c1d343cb82f563f5beb4d0f6f9368c0c95b95ed3cc? s=32&d=mm&r=g) 37. [Paul Gibbs](https://profiles.wordpress.org/djpaul/) 9:08 am _on_ March 8, 2013 38. What are class pages (and their method pages) going to look like? 39. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 10:15 am _on_ March 8, 2013 * Update for anyone reading the thread: have been discussing this with Paul and it raises a wider question of who the code reference is aimed at and what it’s for. The class pages could either a) just be info about the class & methods, or b) have narrative information and explanations like: [https://codex.wordpress.org/Class_Reference/WP_Query](https://codex.wordpress.org/Class_Reference/WP_Query)( I’m leaning towards b, but with a mechanism for filtering out explanatory info, should the developer not want it). * We’re going to get on with the function pages, landing page and archive for now, and discuss this in one of the upcoming doc chats. 40. ![](https://secure.gravatar.com/avatar/496b8d78333d03512679c1c1d343cb82f563f5beb4d0f6f9368c0c95b95ed3cc? s=32&d=mm&r=g) 41. [Paul Gibbs](https://profiles.wordpress.org/djpaul/) 10:09 pm _on_ March 14, 2013 42. Wrote a WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is [http://wp-cli.org/](http://wp-cli.org/) [https://make.wordpress.org/cli/](https://make.wordpress.org/cli/) pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. for the importer: [https://github.com/Automattic/WP-CLI-PHPDoc/](https://github.com/Automattic/WP-CLI-PHPDoc/) 43. Ticket on the WP-Parser project to discuss if to merge/integrate; probably need to discuss at a next dev chat where Ryan and I can both be there. 44. ![](https://secure.gravatar.com/avatar/675b8bc4fb30def27eca21268ac643bc04bbdcf9ac633bd8b922d266f89ea73f? s=32&d=mm&r=g) 45. [pjayo](https://profiles.wordpress.org/pjayo/) 1:52 pm _on_ August 23, 2013 46. Hi. I this still a live thread ? moved elsewhere…. looking to contribute I am … and very interested in being able to programmatically find all functions, actions, filters etc. Notably Mike Little on using the latest ones… [http://www.netmagazine.com/interviews/wordpress-co-founder-keeping-date](http://www.netmagazine.com/interviews/wordpress-co-founder-keeping-date) 47. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 3:03 pm _on_ August 23, 2013 * This project is being actively developed: - The parser is here: [https://github.com/rmccue/WP-Parser](https://github.com/rmccue/WP-Parser) - work is being carried out in WordPress 3.7 to update the docblocks: [https://make.wordpress.org/core/2013/08/09/better-inline-docs-for-3-7/](https://make.wordpress.org/core/2013/08/09/better-inline-docs-for-3-7/) - we’re also compiling a list of tasks for the functionality for the code reference itself. I’ll be posting about that soon. 48. ![](https://secure.gravatar.com/avatar/675b8bc4fb30def27eca21268ac643bc04bbdcf9ac633bd8b922d266f89ea73f? s=32&d=mm&r=g) 49. [pjayo](https://profiles.wordpress.org/pjayo/) 1:54 pm _on_ August 23, 2013 50. PS top right – the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org to the tags for code reference should be hyphenated ? [https://make.wordpress.org/docs/tag/codereference/](https://make.wordpress.org/docs/tag/codereference/) delete this comment if not //p 51. * ![](https://secure.gravatar.com/avatar/78e12b0e0fd945bd7d661af2b0ca95c1509d09a7a1f528ded21bbd604192c662? s=32&d=mm&r=g) * [Siobhan](https://profiles.wordpress.org/siobhan/) 3:05 pm _on_ August 23, 2013 * fixed. Thanks! ### Leave a Reply 󠀁[Cancel reply](https://make.wordpress.org/docs/2013/03/07/better-wordpress-code-reference/?output_format=md#respond)󠁿 You must be [logged in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fmake.wordpress.org%2Fdocs%2F2013%2F03%2F07%2Fbetter-wordpress-code-reference%2F&locale=en_US) to post a comment. # Post navigation [← Docs Chat 6th March](https://make.wordpress.org/docs/2013/03/05/docs-chat-6th-march/) [Theme Developer Handbook Reporting Thread →](https://make.wordpress.org/docs/2013/03/08/theme-developer-handbook-reporting-thread/)