1

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
  • what language are you asking about?
    – gnat
    Commented Jan 17, 2015 at 16:39
  • @gnat php in this case, but its for the most languages right
    – Bas
    Commented Jan 17, 2015 at 17:37

2 Answers 2

4

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 VM\compile.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="doc\IEnumerable.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
  • Could you provide an example in your answer?
    – Bas
    Commented Jan 17, 2015 at 20:12
  • Example added... Commented Jan 17, 2015 at 20:29
0

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 Psr\Http\Message\MessageInterface.

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.