Implement WordPress-like documentations // `Magic::argType()`

[pretzlaw]

As seen on https://cloud.githubusercontent.com/assets/5202330/26426602/0f72f554-40e2-11e7-8873-30b873310746.png this PHPStorm extension can make use of doc comments:

Of course there are different types of documenting an array:

Can you please support this one way of array-description too? It would be loved by all WP devs I guess ;-)

more complex example: https://github.com/WordPress/WordPress/blob/master/wp-includes/class-wp-query.php#L664

Also note for the marked line: Within the key 'meta_query' there is another structure nested that can be found here https://github.com/WordPress/WordPress/blob/master/wp-includes/class-wp-meta-query.php#L106

This could be solved by following a "See WP_Meta_Query" keyword and parsing the constructor of this class. Methods may be referenced too (e.g. "See WP_Query::parse_query() for all" as shown in the image above ).

[klesun]

Thanks, sounds like a very good feature. I'll try to get to it within few weeks.

[klesun]

Lol, there was actually almost identical format supported for ages: https://github.com/klesun/deep-assoc-completion/issues/37

I guess, I'll just tweak it a bit...

[klesun]

Basic support released in 2020.04.22.001

One thing I could not figure out yet though, how do you describe an array of associative arrays with this format? Like:

$arr = [
    ['key1' => 3, 'key2' => 5],
    ['key1' => 1, 'key2' => 8],
]

Is this what you use the nested format you linked in the description for?

* @param array $arr {
*     @type array {
*         @type int $key1
*         @type int $key2
*     }
* }

[pretzlaw]

Is this what you use the nested format you linked in the description for?

Yee. Something like that. There are some nested things but not documented in the "usual doc-comment" way. It is more like "See Yaba\Daba::doo()" which then describes the next level.

For example:

[ // see https://github.com/WordPress/WordPress/blob/master/wp-includes/class-wp-query.php#L627
  'author' => 'barney',
  'meta_query' => [ // documented on line 664 it says: "See WP_Meta_Query." (meaning WP_Meta_Query::__construct() )
    // from here on see https://github.com/WordPress/WordPress/blob/master/wp-includes/class-wp-meta-query.php#L106
    'relation' => 'AND',
    [ // nested array as documented
      'key' => 'bam',
      'value' => 'BAM!',
    ],
    [ // yes, there can be multiple 
      'key' => 'type',
      'value' => 'comic',
    ],
    'a-wild-key-appears' => [ // may have keys but this can be ignored I guess
      'key' => 'year',
      'value' => 'damn old',
    ],
  ]

Hope this gives an insight on nesting. There are several references saying "See ..." so the nested array/structure is documented somewhere else. Fingers crossed that this is can be parsed, followed and appended to the deep-assoc-completion .

Does that help / answer your question?

[klesun]

Thanks. Sorry, looks like I misunderstood what you meant by "nesting". What I wanted to know was the official format WordPress uses to describe an array of arrays, but I guess I better just google this out myself.

I did not initially grasp that by following a "See WP_Meta_Query" keyword you meant to do this automagically. To be honest, I'm not sure that parsing such free-form part of the comment is a good idea. If there are not many such references in WordPress docs, maybe it would be simpler for me to just hardcode in the plugin the logic for all WordPress classes/functions with such references. I did a similar thing for built-in php functions.

I could also possibly add support for some Magic::argType(0, [WP_Meta_Query::class, '__construct']) you could use yourself in a .phpstorm.meta.php file to extend the type info of WP_Query::parse_query(), like:

expectedArguments(WP_Query::parse_query(), 0, [
    'meta_query' => Magic::argType(0, [WP_Meta_Query::class, '__construct']),
]);

(though this would be still needed to be implemented on my part)

[pretzlaw]

To be honest, I'm not sure that parsing such free-form part of the comment is a good idea

We thought so too, but having a pattern or finding a well established could do so. Perhaps you can make such behaviour optional (like providing a regexp in the settings). There are round about 40 references to different other places where the documentation goes on and they surely change from time to time.

The idea with .phpstorm.meta.php is absolutely charming, but needs a lot of hands on an will be carried around in millions of repositories all with the same content. But you could have this built-in:

If you can provide a helper like the Magic::argType and/or give a class specially for WP, then we would totally help maintaining this thing. Be aware that the nesting may change from version to version - which is additional work to do.

Would this be a way for you? A class like the one for PHP but for WordPress and we configure the references. With each new minor release of WP.

[klesun]

Sounds great! Though I'll be able to get to it only in few weeks, when I'm not so busy with the vscode port