Wednesday, August 23, 2006

A Not So Simple Example

What follows in this entry is "a not so simple example" that I have reconstructed from memory.  It is intended to serve as a "bad example". (Kids, do not try this at home.  Closed course.  Professional drivers.  Buyer assumes all risk.)  I will let you savor this one for a while and in my next blog entry I'll list at least some of the problems I see in how this interface is defined.

 

namespace Interfaces
{
/// <summary>
/// This is the initial cut at the document management interface.
/// </summary>
public interface IManageDocument
{
/// <summary>
/// Identify where the document can be found.
/// </summary>
/// <param name="location">The string value
/// that locates the document.</param>
void SpecifyDocumentLocation(string location);

/// <summary>
/// Prepare the document for use.
/// </summary>
/// <returns>True, if there were no problems;
/// false, otherwise.</returns>
bool Open();

/// <summary>
/// Retrieve the last error message.
/// </summary>
/// <returns>If the last operation failed, an error message;
/// if the last operation succeeded, an empty string.</returns>
string GetLastErrorMessage();

/// <summary>
/// Retrieve the title of the document.
/// </summary>
/// <returns>The overall title of the document.</returns>
string GetTitle();

/// <summary>
/// Release the document.
/// The document must be opened again before any further use.
/// </summary>
void Close();

/// <summary>
/// Position the TOC to the first entry.
/// </summary>
void ResetTOC();

/// <summary>
/// Position to the next TOC entry after the current one in a
/// depth-first search (that is limited to the specified
/// number of levels).
/// </summary>
/// <param name="maximumLevel">The maximum number
/// of levels to decend.</param>
/// <returns>False, if the TOC position is after
/// the last TOC entry;
/// True,if there is a current TOC after the positioning.</returns>
bool GetNextTOC(int maximumLevel);

/// <summary>
/// Retrieves the document index for the current TOC entry.
/// </summary>
/// <returns>A string that can be used
/// to position the document to a
/// specific location within the document.</returns>
string GetCurrentTOCID();

/// <summary>
/// Retrieves the title string of the current TOC.
/// </summary>
/// <returns>A string representing
/// the current TOC entry title.</returns>
string GetCurrentTOCTitle();

/// <summary>
/// Retrieves the level of the current TOC entry.
/// </summary>
/// <returns>An integer representing
/// the level of the current TOC entry.</returns>
int GetCurrentTOCLevel();

/// <summary>
/// Position the document to the location
/// specified by the input parameter.
/// </summary>
/// <param name="documentIndex">A string value returned
/// by the <see cref="GetCurrentTOCID"/> method
/// or one of the values
/// returned by the <see cref="GetIndices"/> method.</param>
/// <returns>True, if the supplied index corresponds
/// to a section within the document;
/// False, if the interface could not
/// find the indicated section.</returns>
bool PositionToIndex(string documentIndex);

/// <summary>
/// Position to the next paragraph in the indexed section.
/// </summary>
/// <remarks>The typical processing is
/// to call <see cref="PositionToIndex"/>
/// to position to the first
/// paragraph in the document section,
/// read the text with <see cref="GetCurrentParagraphText"/>
/// and loop through the remaining paragraphs
/// using <see cref="PositionToNextParagraph"/>.</remarks>
void PositionToNextParagraph();

/// <summary>
/// Rewind to the first paragraph within
/// the current section. This is equivalent to a call to
/// <see cref="PositionToIndex"/>
/// using the last document index.
/// </summary>
void RepositionToFirstParagraph();

/// <summary>
/// Get the text of the current paragraph.
/// </summary>
/// <returns>A string representing
/// the current paragraph.</returns>
string GetCurrentParagraphText();

/// <summary>
/// Retrieve a set of zero or more document
/// indices that represent the locations within
/// the document where the lookup parameter value appears.
/// </summary>
/// <param name="lookup">The "index term"
/// to search for.</param>
/// <returns>An array of document indices.</returns>
string[] GetIndices(string lookup);

}
}

0 Comments:

Post a Comment

Links to this post:

Create a Link

<< Home