Each getter must have description with @return annotation.

[fooman]

The autogenerated code for Interceptor classes is using the inheritdoc notation. This then does not pass checks on the class for correct docblock description and return type. For details to reproduce and confirmation this change fixes it see https://gist.github.com/mzeis/11a7231cd67a5216ec47

[okorshenko]

Hi @fooman
Thank you for you contribution!
Please, checkout the latest available version (0.42.0-beta4). Your plugin should work on this version. There is no sense to merge this PR yet, since it just hides implementation errors (when someone relies on the API interface implementations instead of API interface)
The main idea is that our API clients should not know about API interface implementation. Our code must rely on the API interfaces only.
Please take a look at https://github.com/magento/magento2/blob/develop/app/code/Magento/Customer/Model/Customer/Mapper.php#L39

[fooman]

@okorshenko I can confirm that the error message indeed has gone away with beta4. Could you please explain what you meant with

The main idea is that our API clients should not know about API interface implementation. Our code must rely on the API interfaces only.

The plugin was intercepting

<type name="Magento\Customer\Api\Data\CustomerInterface">

Could you confirm if this is a correct/valid approach or if something else should have been chosen.

Any documentation / link to documentation that you can provide in terms of what to intercept when would be great.

[okorshenko]

Could you please explain what you meant with

I meant that if you want to convert object to array using method Magento\Framework\Api\ExtensibleDataObjectConverter::toNestedArray($dataObject, $skipCustomAttributes, $dataObjectType) you can not rely on provided data object class, since this class can implements several different interfaces. You have to specify valid $dataObjectType that is one of the stabel API interface. In this case we relies on the API interface only, but not on one of the implementation of the API interface. Resulting we don't need to know about autogenerated interceptor interfaces (such as method ___callParent).
Your error was caused by this line of code https://gist.github.com/mzeis/11a7231cd67a5216ec47#file-error-L6:

#4 /var/www/magento2/app/code/Magento/Customer/Model/Customer/Mapper.php(38): Magento\Framework\Api\ExtensibleDataObjectConverter->toNestedArray(Object(Magento\Customer\Model\Data\Customer\Interceptor))

But luckily we have already fixed this issue on the our code base. Please, enjoy :)

Could you confirm if this is a correct/valid approach or if something else should have been chosen.

I confirm that this is valid approach.

Any documentation / link to documentation that you can provide in terms of what to intercept when would be great.

I'm not sure that we have some documentation that describes what to intercept and when. This depends on your concrete case. The general approach/best practices are:

• pluginize stable API interfaces, if it is available (as you did in your code for Magento\Customer\Api\Data\CustomerInterface)
• if API interface is not implemented, it is highly recommended to intercept the class method that is the most closer to functionality that you want to intercept (for instance, you don't need to intercept Layout model if you want to change behavior of one of the generated Block)
• it is discouraged to use around interception strategy in the plugin classes without call of proceed closure (since this is a potentially conflicting modification. In this case you may break other 3rd party plugin's logic)