Well-documented code should be a given nowadays. In the world of PHP, the standard for documenting is the so-called PHPDoc, whereas .NET uses XMLDoc. In this article, we’ll take a look at how all this is connected with PeachPie.
Intro
PHP code is generally documented using PHPDoc, an informal standard for commenting PHP code adapted from Javadoc. .NET, on the other hand, uses XML Doc, wherein the C# compiler creates magic XML files annotating the compiled DLL, and various tools can subsequently extract documentation data from them. Not only can you create a complete programming documentation of your whole project from these XML files, but Visual Studio’s IntelliSense can later fill in information about classes, methods, method parameters, constants etc.
PeachPie
This is where PeachPie comes into play. The project compiles PHP into a .DLL file – wouldn’t it be great to generate the same data to be used by .NET tooling (including IntelliSense)? This is exactly one of PeachPie’s features. To make a long story short, the compiler generates an XMLDoc from the collected PHPDoc comment blocks from the source .php files.
Furthermore, the generated XML documentation file is enriched by the results of PeachPie’s type analysis in order to make the documentation as useful as possible, for example to be used by IntelliSense. This is, in fact, the main benefit of this process – using PHPDoc comments to help IntelliSense.
XMLDoc
XMLDoc is created together with the generated DLL file and contains data that was collected from PHPDoc and associated with metadata in the compiled DLL. For more information, see the XMLDoc documentation.
To illustrate this, let’s take a look at the following example in PHP:
[code language=”php”]
/**
* Core class used to implement an admin screen API.
*/
final class WP_Screen {
/**
* Fetches a screen object.
*
* @since 3.3.0
*
* @static
*
* @global string $hook_suffix
*
* @param string|WP_Screen $hook_name Optional. The hook name (also known as the hook suffix) used to determine the screen.
* Defaults to the current $hook_suffix global.
* @return WP_Screen Screen object.
*/
public static function get( $hook_name = ” ) {
[/code]
And this is what PeachPie generates out of the above PHP code:
[code language=”xml”]
<member name="T:WP_Screen">
<summary>
Core class used to implement an admin screen API.
</summary>
</member>
<member name="M:WP_Screen.get(Pchp.Core.Context,Pchp.Core.PhpValue)">
<summary>
Fetches a screen object.
</summary>
<param name="hook_name" type="string|WP_Screen">Optional. The hook name (also known as the hook suffix) used to determine the screen.
Defaults to the current $hook_suffix global.</param>
<returns>Screen object.</returns>
</member>
[/code]
Thanks to this, the C# editor can offer the documentation of the compiled PHP symbols (members, types, fields, constants) all on its own.
IntelliSense
With this feature, PeachPie extends its already vast interoperability options by another important element. Since an XML documentation file is created together with the DLL file, Visual Studio (and any other tool for .NET development) can make use of the annotations of the compiled code’s individual symbols. Let’s try referencing a PHP project (i.e. its compiled DLL) by a C# project, and use one of its compiled PHP classes in C#:
So what are the consequences of this?
First of all, definitely add comments to your code. Every developer, not just yourself, will appreciate it when they will be using your code. More importantly, however, the IDE understands XMLDoc, looks for it together with the compiled DLL and – without the need of configuring anything – extends IntelliSense by the documentation.
For the more curious ones among you – the image also reveals that a majority of PHP code doesn’t have strongly typed parameters and function return values. Those values that can assume any type are translated by the compiler as PhpValue. If we add types in the PHP code (type hints for parameters, PHP7 return types for function return values), the signature will be modified accordingly.
The next characteristic of the implementation is the first parameter Context, which is required by the PHP code. We usually don’t come across this parameter, particularly in static methods and class constructors.
XMLDoc and NuGet
If you’re creating a NuGet package out of the compiled PHP project, don’t forget to include the XMLDoc. Our documentation has a demo of how to turn on the generation of XMLDoc, or check out one of our previous articles, where we show the NuGet creation process.
The best part about this whole mechanism is that it works automatically; you essentially don’t have to do anything.