Documenting Contributions to DPCL

When you contribute a new class or new functions to an existing class in DPCL, it is important that you also contribute documentation for the additions you have supplied. The DPCL Project has two HTML-formatted "books" (the DPCL Class Reference and the DPCL Programming Guide) that document the class library. The DPCL Class Reference provides detailed, alphebetically-ordered information about each DPCL function, while the DPCL Programming Guide provides task-oriented instructions on building analysis tools on top of DPCL. To document your contributions to DPCL, you will need to:

Creating Reference Information for the DPCL Class Reference

The DPCL Class Reference is an alphabetically-ordered collection of man-page style information about each DPCL class and function. To create the information to be inserted into this HTML-formatted "book", you should:
  1. Save a copy of one of the DPCL Class Reference "chapters" to your local machine so that you may modify it to document your contributed class/functions. Using an actual chapter from the existing book helps ensure that your new documentation will be consistent with the existing documentation.

    Each class in the DPCL Class Reference is documented in a separate "Chapter"/HTML file. To save a copy of the file:

    1. In your favorite web browser, open a particular chapter of the DPCL Class Reference.
    2. Select the browser's File --> Save As... menu option.

      Doing this opens a standard Save File dialog.

    3. In the dialog, give the file a name appropriate to the contribution you'll be documenting, and click the Save command button.
  2. Using your favorite HTML or text editor, edit the file you have copied to document the additions you are contributing to the DPCL project. If you are contributing an entire new class, document the entire class (its supporting data types, constructors, and each of its functions) in this file. If you are contributing individual functions to an existing class, delete the extraneous information in the file pertaining to class data types and constructors, and modify the function information.

    When documenting your contributions to the DPCL project, take care that your documentation is consistent with the existing documentation. Since you are using an existing file as a base, this should be easy. Take care that you do not change the heading levels (<H1>, <H2>, <H3>, etc), and also use highlighting consistent with the rest of the book. The DPCL Class Reference uses the following highlighting conventions.
    Convention Usage
    bold (<B></B>) Bold words or characters represent system elements that you must use literally, such as: function names, file names, flag names, path names, etc.
    italic (<I></I>) Italicized words or characters represent variable values that you must supply.

    Italics are also used for book titles and for general emphasis in text.

    constant width (<TT></TT>) Examples and information that the system displays appear in constant-width typeface.

    Creating Conceptual and Task-Oriented Information for the DPCL Programming Guide

    The DPCL Programming Guide provides both conceptual and task-oriented information on the various classes/functions of DPCL. To create the information to be inserted into this HTML-formatted "book", you should first of all familiarize yourself with the existing book. By familiarizing yourself with the way it presents information, you will be able to more easily create documentation for your contribution that matches the book's tone and approach. Once you are familiar with the existing book, you can:

    Create Conceptual Information for "Chapter 2: What are the DPCL Classes?"

    The chapter "What are the DPCL Classes?" in the DPCL Programming Guide provides conceptual information for each of the DPCL classes in turn. Each class description ends with a quick-reference table summarizing all of the functions in the class. Here is a partial outline of the chapter. Notice that cases where there are several classes that are similar or related (such as the ProbeExp, ProbeHandle, and ProbeModule classes), they are grouped under the same section in the chapter, while other classes (such as the Phase class) appear in their own section.

  3. Chapter 2. What are the DPCL classes?
  5. What are the Process, Application, and PoeAppl classes?
  6. What is the Process class?
  7. What is the Application class?
  8. What is the PoeAppl class?
  10. What are the ProbeExp, ProbeHandle, and ProbeModule classes?
  11. What is the ProbeExp class?
  12. What is the ProbeHandle class?
  13. What is the ProbeModule class?
  15. What are the SourceObj and InstPoint classes?
  16. What is the SourceObj class?
  17. What is the InstPoint class?
  19. What is the ProbeType class?
  20. What is the Phase class?
  21. What is the AisStatus class?
    22. To create the information for your contribution to be inserted into this "chapter", you should:
    1. Save a copy of the chapter "What are the DPCL classes?" to your local machine so that you may modify it to document your contribution to DPCL.

      To save a copy of the HTML file that contains the section:

      1. In your favorite web browser, open the "What are the DPCL Classes?" chapter.
      2. Select the browser's File --> Save As... menu option.

        Doing this opens a standard Save File dialog.

      3. In the dialog, give the file a name appropriate to the contribution you'll be documenting, and click the Save command button.
    2. Using your favorite HTML or text editor, edit the file you have copied to document the additions you are contributing to the DPCL project.
      If your are contributing: Then:
      Several related classes Modify one of the existing sections of the chapter that describe two or more related or similar classes (such as the section "What are the Process, Application, and PoeAppl classes?" or the section "What are the SourceObj and InstPoint classes?")
      a single new class Modify one of the existing sections of the chapter that similarly describe a single class (such as the section "What is the Phase class?" or the section "What is the AisStatus class?")
      new functions for an existing DPCL class Modify the section that documents the class for which you are contributing new functions. You will likely only need to modify the quick-reference table that summarizes the function in a class.

      When making additions to the DPCL Programming Guide, take care that your documentation is consistent with the existing documentation. Since you are using the existing file as a base, this should be easy. Take care that you use highlighting and conventions that are consistent with the rest of the book.

      The DPLC Programming Guide uses the following highlighting and style conventions.

    3. Headings, figure captions, and table captions use initial capitalization only, and are otherwise written in lowercase. Class names, however, retain their standard capitalization. For example, "What is the PoeAppl class?" and "Application class function summary"
    5. Subroutine names appear in constant-width typeface (using the <TT></TT> tags).
    7. The scope resolution operator (::) is used when referring to DPCL functions. The DPCL Programming Guide does this for the following two reasons:
      • First of all, the documentation uses the scope resolution operator for the same reason a program might -- to remove ambiguity when multiple classes contain identically-named member functions. For example, since both the Application class and the Process class have a member function connect, the book refers to these functions as Application::connect and Process::connect to avoid ambiguity.
      • Secondly, the book also uses the scope resolution operator in a more general way to simply show the class that contains a particular member function; it does this even when the function name is unique within the entire class library. The ambiguity being addressed in these cases is within this book's text only, and not within DPCL's programming interface. For example, even though the function name add_process is unique within the entire class library, the book will, for clarity, still refer to it as Application::add_process.

      Create task oriented information and example

      The DPCL Programming Guide contains sections called "Standard DPCL Programming Tasks" and "Additional DPCL Programming Tasks" that contain chapters on performing specific tasks using DPCL. The existing chapters document such tasks as "Connecting to or starting the target application processes", "Creating probes" and "Handling signals and file descriptors through the DPCL system". If your contributions to DPCL enable analysis tools built on DPCL to accomplish a significant new task, you might want to consider adding a new chapter to the section entitled "Additional DPCL Programming Tasks". The purpose of this new chapter will be to:
      • show how the various new class(es) and/or functions you have added to DPCL work together to enable an analysis tool to accomplish a specific task.
      • provide a code example that illustrates how to use the new class(es) and/or functions

      To create a new chapter to be inserted into the "Additional DPCL Programming Tasks" section of the DPLC Programming Guide, you should:

      1. Save a copy of one of the chapters in the "Additional DPCL Programming Tasks" section of the DPLC Programming Guide to your local machine so that you can modify it to document your contributed class/function. Using an actual chapter from the existing book helps ensure that your new documentation will be consistent with the existing documentation. To save a copy of a chapter:
        1. In your favorite web browser, open a particular chapter of the "Additional DPCL Programming Tasks" section of the DPLC Programming Guide.
        2. Select the browser's File --> Save As... menu option.

          Doing this opens a standard Save File dialog.

        3. In the dialog, give the file a name appropriate to the contribution you'll be documenting, and click the Save command button.
      2. Using your favorite HTML or text editor, edit the file you have copied to document the programming task associated with the additions you are contributing to the DPCL project. Take care that you follow the highlighting and style conventions used throughout the DPCL Programming Guide. These conventions are outlined above.