Version 11 (modified by martin, 7 years ago)

--

Source Docs

On this page the community is welcome to list tasks that will improve the usability of the OpenSceneGraph library by improving the documentation of its source code, in particular its classes/methods/fns/enums.

Note that the aim of this initiative should not be to reproduce the OSG book that is in-the-making. Rather, it should focus on the interface aspects of the OSG source code. It should also not be concerned with spelling or grammar, as this is covered by other tasks (SpellingBee?), increases the level of effort needed (and therefore decreases the number of potential contributors), and does not provide usability value (except where the spelling or grammar mistake changes the meaning of the information, which is rare). Note also that this documentation effort should make it as easy as possible for any OSG user to contribute.

I propose several passes through the source code, each focussing on a specific aspect of documentation. Each pass should be a clear and simple task that is limited in scope, time, and well-defined, and possibly tied to release dates.

The work for each pass should specify the following:

  1. What to document
  2. Who and how can add documentation, who validates the additions/changes and how
  3. When the effort ends; a discussion can take place to see what should be next pass (if any)

Suggested assignments:

change validation
Robert Osfield
] regular email reminder
tbd (!Oliver Schoenborn volunteers)
update locks
tbd

Suggested first pass:

  1. Document the osg namespace: classes, methods/functions, enums, and method/function arguments. Specifications:
    • Only a one liner for each: say what it is 'used' for (rather than what it is)
    • Don't bother documenting the obvious; e.g.
  2. Who/how add, who/how validate:
    • anyone can add, by emailing modified source file to Robert Osfield
    • a list of items to be documented can appear on this wiki, the coarseness is left up to the lead
    • should probably have a locking mechanism: users who wish to contribute can mark an item so others know they are working on it; the mark is the date and author name; the mark expires after 2 days, at which point the author can still send changes in, but if meanwhile someone else has sent in edits, merging will be left entirely up to Robert (to do or to discard latest etc)
    • as items get documented, Robert removes them (or notifies someone to do so) from this wiki
    • an email can be sent out to the list periodically to remind users of the potential for easy contribution
  3. Target date: next release

Items:

  1. AnimationPath
  2. AnimationPathCallback
  3. ApplicationUsage
  4. ArgumentParser
  5. Array
  6. ArrayVisitor
  7. AutoTransform
  8. !Billboard
  9. BlendColor
  10. BlendEquation
  11. BlendFunc
  12. BoundingBox
  13. BoundingSphere
  14. Box

As mentioned at the top of this page, please feel free to contribute your thoughts/opinions on any of the above by editing this page.