Dev/Documentation

  1. Introduction
  2. General
  3. Contents
    1. High-level docs
    2. API
  4. Building documentation

Introduction

Documentation and examples are crucial to get things going. Especially since OpenSG, at the moment, has many advanced features but little documentation on them.

General

  • The user should only have to download one package, the full OpenSG, where there should be locally contained docs explaining everything
  • Website should link to precompiled doc for all major releases and HEAD/trunk.
  • Documentation needs to have one good Front Page (tm)!
    • Link to 'tutorials', 'examples', 'user guide', opensg-web, etc.
    • Provide a snapshot of trac-wiki? (might be hard to resolve links properly, unless all doc is snapshotted from server)
  • Recruit a "documentation team" to work on a sprint to document as much as possible.

Contents

High-level docs

There needs to be a developer guide that explains the design and inner workings of the current core. This should *not* be in extreme detail since we need to make sure it stays up to date. It may just be references to doxygen generated documentation that gives a mental framwork for how things hook together. (ie. how all the internals connect and work together)

API

  • Too many classes have no documentation and then the user has no idea what they are for.
  • Users currently have to reverse-engineer the API's and usage rules.
  • Users need not see implementation details.

Solutions:

  • All classes should have some description of what they do and what they are for. #59.
  • Split doxygen doc into two:
    • User (does not change OpenSG useful as quick reference)
    • Developer (works within OpenSG, or user who needs more info).
  • Autogenerate docs on server.
  • Develop documentation standard. #62
  • Make documentation work a natural part of coding:
    • Convince developers to document the code as they write it and keep the docs up to date.
    • Write some test to see if classes/functions are untested. Post report to mail-list (similar to boost).
  • Define the "important classes", start documenting them and move on from there.

Investigate setting up a 'doc-police-bot' that reports documentation status? /ML

Building documentation

  • Doxygen is quite slow on large projects, and OpenSG is indeed large.
  • Building API docs takes a _long_ time.

Proposal:

  • Split different parts into different doxygen runs. Cross-reference.
  • Build documentation in dailybuild (minor doc changes in trunk need not be tested by user then).