[MESOS-2478] Document libprocess

• Type: Epic
• Status: In Progress
• Priority: Major
• Resolution: Unresolved
• Component/s: libprocess
• Labels: documentation mesosphere
• Epic Name: Document libprocess
• Assignee: Unassigned
• Reporter: Bernd Mathiske
• Shepherd: Benjamin Hindman
• Created: 11/Mar/15 15:33
• Updated: 19/Dec/15 00:22

Description

We can gain development velocity by augmenting the documentation of the central work horse library of Mesos: libprocess. Specifically, there is opportunity to:

• Give an overview of the library's purpose and contents.
• Explain the underlying design goals and principles.
• Explain file/class/feature purposes and how they relate to each other.
• Specify parts of the library's API, both its interfaces/signatures and the expected usage protocols/patterns.
• Point out important invariants, constraints and limitations.
• Provide some example usage code.

Let's use Doxygen so that we can keep the documentation effort close to the source code and facilitate keeping both in sync. Thus we can create both immediately useful source code comments and we can also generate an API reference manual, which can be used both online and offline.

This means that we will deviate from the current source code comment format and switch over to Doxygen format for all publicly visible parts of libprocess, and potentially also for the rest of it. So the first task is to come up with a specific Doxygen style that we then want to apply consistently.

Issue Links

• blocks: MESOS-1186 Generate C++ docs with doxygen.
• relates to: MESOS-2465 Add links to libprocess readme