libpostal/php-postal not being seen within IDE

here's the php wrapper https://github.com/openvenues/php-postal

Hi there,

You can create a stub file that PhpStorm will understand. All stuff from PHP core that is known to PhpStorm is done this way (see for yourself: https://github.com/JetBrains/phpstorm-stubs)

Stub file is basically a PHP file with class/functions/constants/variables/etc definitions (with proper PHPDoc comment blocks) but all function/method bodies are empty.

You may check Google and/or GitHub -- maybe somebody have created them for your library already.

Feel free to submit the feature request to our tracking system here: http://youtrack.jetbrains.com/issues/WI#newissue=yes .

You can also create a stub and we (and other users) would be glad to to accept your contribution! Please follow instructions at https://github.com/JetBrains/phpstorm-stubs/blob/master/CONTRIBUTING.md .

Thanks for link and advice Andriy and Vladimir! I'll build a stub and post it here when I get it working correctly...

ok this:
<?php
namespace Postal;
// Start of libpostal v.

class Expand
{
 /**
 * Expand a postal address
 * @link https://github.com/openvenues/php-postal
 * @param string $address [required] <p>
 * The address is a partial or whole international postal address.
 * </p>
 * <p>
 * <p>
 * The address can be abbreviations or whole words in any language supported
 * by UTF-8 and this function expands the abbreviations in the address to whole words.
 * </p>
 * </p>
 * @return array of possible address expansion strings with
 * abbreviations expanded to whole words.
 * @since 5.5
 */
 public static function expand_address($address){}
}
class Parser
{
 /**
 * Parse a postal address into array
 * @link https://github.com/openvenues/php-postal
 * @param string $address [required] <p>
 * Parses address into best guess components
 * </p>
 * @return array of indexes named after address components, with values of
 * corresponding components parsed from input address string.
 * @since 5.5
 */
 public static function parse_address($address){}
}

// End of libpostal v.
?>

running as a stub gave me the expected result:

\Postal\Expand::expand_address($address)

and

\Postal\Parse::parse_address($address)

validate correctly in the IDE and also the code runs correctly.
I'm not sure if that is the way I'm supposed to code a stub though...

>I'm not sure if that is the way I'm supposed to code a stub though...

Overall it's all good -- you are going in the right direction.

The rest is just a matter of making it better/more practical in PHPDoc aspect: make it a bit easier to read (for others) and write (for yourself) as well as quality of the description itself.

• No real need to use <p>...</p> everywhere. This usage comes from the tool that was used to create stubs for PhpStorm files.
• Makes sense to use <p> if you want to make it visible separation of one part from another (so that IDE (View | Quick Definition) renders it with better paddings between the lines).
• If you have @link .. then it better point to online documentation for that specific function. If there is no such online doc -- use it for a class or omit altogether.
• @since tag is used mainly for PHP version (since what PHP version this entity/method available). If it's related to libpostal version ... then it will be better if you use "@since libpostal 5.5" instead of just "@since 5.5"
• No need for [required] part -- all params are required by default (unless it's needed for some other reason)
• If you have optional parameters -- use [optional] as first word in parameter description
• You can also typehint parameters/return value using PHP way. Keep in mind that some of it will only work if PHP Language Version in IDE is set to version 7.0 or newer.
• @return should have return type and then proper description. "@return array of indexes named after address components,..." is not ideal. "@return array List of indexes ...." sounds better. Another idea -- just use "@return array" and describe actual what's returned separately

My version (shows different things from the list above):

<?php

namespace Postal;

class Expand
{
    /**
     * Expand a postal address.
     * 
     * @param string $address The address is a partial or whole international postal address.
     * <p>The address can be abbreviations or whole words in any language supported
     * by UTF-8 and this function expands the abbreviations in the address to whole words.
     * @return array List of possible address expansion strings with abbreviations
     * expanded to whole words.
     */
    public static function expand_address($address){}
}

/**
 * Parse class description.
 * 
 * @link https://github.com/openvenues/php-postal
 */
class Parse
{
    /**
     * Parse a postal address into array.
     * 
     * <p>Returns array of indexes named after address components with values of
     * corresponding components parsed from input address string.
     * 
     * @param string $address Parses address into best guess components
     * @return array 
     */
    public static function parse_address($address){}
}

The main point is: there will be some stub (so IDE is happy) and some documentation to it (so user can look up at least something -- to get some basic idea of what this method does and what the params are for).

There is no need to make it perfect if you do not wish to share it etc. For your own usage even a version with no description parts at all will do (since you know what this or that method does).