I know how to document a function:
/**
* Prints a greet message to the web page
*/
function greet() {
echo "Hi!";
}
Or describe the usage of a variable:
/**
* @type string $name The user's name
*/
$name = "Bas";
But I don’t know how to document an interface. It requires the classes which implement the interface to have the functions which are inside the interface, and that’s it.
Question
How do you document an interface?
2
Describe the purpose and usage of the interface, and the purpose and usage of the functions in the interface.
Here is an example from the .NET Framework (simplified for brevity). Note the “statement of purpose,” and the specific notes about jitting and internal hacks, things which would not at all be obvious just by looking at the interface code:
// Implement this interface if you need to support foreach semantics.
// Note that T[] : IList<t>, and we want to ensure that if you use
// IList<yourvaluetype>, we ensure a YourValueType[] can be used
// without jitting. Hence the TypeDependencyAttribute on SZArrayHelper.
// This is a special hack internally though - see VMcompile.cpp.
// The same attribute is on IList<t> and ICollection<t>.
public interface IEnumerable<out t=""> : IEnumerable
{
// Returns an IEnumerator for this enumerable Object. The enumerator provides
// a simple way to access all the contents of a collection.
/// <include file="docIEnumerable.uex" path="docs/doc[@for="IEnumerable.GetEnumerator"]/*">
new IEnumerator<t> GetEnumerator();
}
It’s worth noting that some of the documentation you describe in your question is either unnecessary or redundant. Don’t document things that are obvious. Instead, make things obvious so that you don’t have to document them.
Documentation is just one more thing that you have to maintain and keep in sync, so document for the right reasons. Allow the code log to speak for itself, but document the relationships between methods and classes, explain obscure things, and in general be helpful without repeating yourself.
2
Describe the intended meanings and effects of the functions defined by the interface, along with the meanings of any parameters and return values. Code that implements the interface, and code that relies on it need to be written with a shared understanding of those meanings to be useful.
The interface doesn’t just require the classes that implement it to have the functions with the given names and types. It can also require other things of the class, which you can write in English in the documentation. PHP uses nominal typing, rather than structural typing, meaning classes that implement the interface must name it in their implements statement. By doing so they effectively self-certify that they follow any specifications written into the interface’s documentation.
A good example from PHP is PsrHttpMessageMessageInterface.
Of course you need to consider who your audience is, and if they are all your colleagues who can easily talk to you then you don’t need to be quite as detailed
or formal as the Psr interface, but it’s still worth documenting things that might not be obvious.