From 7a86c08ec80c77a56adc991a4cdb462fd17cf4e0 Mon Sep 17 00:00:00 2001
From: Joel Holdsworth <joel@joel-desktop.(none)>
Date: Sat, 29 Nov 2008 16:40:50 +0000
Subject: [PATCH] Added some documentation

---
 src/gui/widgets/timeline-widget.cpp |  3 +++
 src/gui/widgets/timeline-widget.hpp | 25 ++++++++++++++++++++++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/gui/widgets/timeline-widget.cpp b/src/gui/widgets/timeline-widget.cpp
index cf1aeb013..336c67504 100644
--- a/src/gui/widgets/timeline-widget.cpp
+++ b/src/gui/widgets/timeline-widget.cpp
@@ -87,6 +87,7 @@ TimelineWidget::TimelineWidget(model::Sequence* const source_sequence) :
 
 TimelineWidget::~TimelineWidget()
 {
+  // Destroy child widgets
   REQUIRE(body != NULL);
   if(body != NULL)
     body->unreference();
@@ -332,6 +333,8 @@ TimelineWidget::create_timeline_track_from_model_track(
 {
   REQUIRE(model_track);
   
+  // Choose a corresponding timeline track class from the model track's
+  // class
   if(typeid(*model_track) == typeid(model::ClipTrack))
     return new timeline::ClipTrack();
   else if(typeid(*model_track) == typeid(model::GroupTrack))
diff --git a/src/gui/widgets/timeline-widget.hpp b/src/gui/widgets/timeline-widget.hpp
index e216e7c13..63a185be1 100644
--- a/src/gui/widgets/timeline-widget.hpp
+++ b/src/gui/widgets/timeline-widget.hpp
@@ -163,14 +163,37 @@ private:
 
   void update_tracks();
   
+  /**
+   * Ensures timeline UI tracks have been created for every model track
+   * present in sequence.
+   **/
   void create_timeline_tracks();
   
+  /**
+   * Iterates through a branch of tracks, recursing into each sub-branch
+   * creating UI timeline tracks for each model track, if they don't
+   * already exist in trackMap.
+   * @param list The list of model tracks to interate through.
+   **/
   void create_timeline_tracks_from_branch(
     const std::list<model::Track*>& list);
-    
+  
+  /**
+   * Creates a timeline UI track to correspond to a model track.
+   * @param model_track The model track to create a timeline track from.
+   * @return The timeline track created, or NULL if model_track has an
+   * unreckognised type (this is an error condition).
+   **/
   static timeline::Track* create_timeline_track_from_model_track(
     model::Track *model_track);
   
+  /**
+   * Looks up a timeline UI track in trackMap that corresponds to a
+   * given model_track.
+   * @param model_track The model track to look up.
+   * @returns The timeline UI track found, or NULL if model_track has no
+   * corresponding timeline UI track (this is an error condition).
+   **/
   timeline::Track* lookup_timeline_track(model::Track *model_track);
   
   void update_scroll();