How to classify an operation?

When documenting APIs with iDocIt!, you classify each documented operation. There are several categories such as Searching Operation or Mathematical Operation. This classification is easy when the classified operation does only one activity, e.g. computing a value. From my experience, you will find such cases rarely in your daily business.

Right now I develop a new extension for iDocIt!'s Java support. With this extension it is possible to generate a very compact Javadoc-representation of iDocIt's thematic roles. When implementing JUnit-Test cases for it I had to document (and classify) this method:

/**

 * Adds a new {@link Documentation} with the given attributes to the given

 * {@link SignatureElement}.

 * 

 * @param element

 *            [DESTINATION]

 * @param addresseeName

 *             [ATTRIBUTE] Used in the new documentation

 * @param thematicRole

 *            [ATTRIBUTE] Used in the new documentation

 * @param docText

 *            [ATTRIBUTE] Used in the new documentation

 * 

 * @thematicgrid Putting Operations

 */

public static void addDocumentation(SignatureElement element, String addresseeName,

String thematicRole, String docText)

{

 List<Addressee> addressees = createReferenceAddresseeList(addresseeName);

 Map<Addressee, String> docs = createComparisonDocumentation(addresseeName);

 docs.put(addressees.get(0), docText);

 Documentation documentation = new Documentation();

 documentation.setAddresseeSequence(addressees);

 documentation.setThematicRole(new ThematicRole("COMPARISON"));

 documentation.setSignatureElementIdentifier("records");

 documentation.setDocumentation(docs);

 element.addDocpart(documentation);

}

As you see, the method creates a new instance of Documentation and then adds it to the given SignatureElement. From my point of view, it's first part should be classified as Creation Operation and the last row is a Putting Operation.

Due to my posting Second extension of my thoughts ... I would classify this operation as Putting Operation, because its final goal is to add a documentation to the given SignatureElement. I think, this rule could be generalized:

If you have an operation composed of several operation categories, choose the last one as catgeory for the composite-operation.