tutorial: Improve documentation comments a bit

gst-plugin-tutorial/src/rgb2gray.rs

@@ -103,15 +103,20 @@ impl Rgb2Gray {
     }
 }
 
+// This trait registers our type with the GObject object system and
+// provides the entry points for creating a new instance and setting
+// up the class data
 impl ObjectSubclass for Rgb2Gray {
     const NAME: &'static str = "RsRgb2Gray";
     type ParentType = gst_base::BaseTransform;
     type Instance = gst::subclass::ElementInstanceStruct<Self>;
     type Class = subclass::simple::ClassStruct<Self>;
 
+    // This macro provides some boilerplate
     glib_object_subclass!();
 
-    // Called when a new instance is to be created
+    // Called when a new instance is to be created. We need to return an instance
+    // of our struct here.
     fn new() -> Self {
         Self {
             cat: gst::DebugCategory::new(
@@ -135,6 +140,10 @@ impl ObjectSubclass for Rgb2Gray {
     //
     // Our element here can convert BGRx to BGRx or GRAY8, both being grayscale.
     fn class_init(klass: &mut subclass::simple::ClassStruct<Self>) {
+        // Set the element specific metadata. This information is what
+        // is visible from gst-inspect-1.0 and can also be programatically
+        // retrieved from the gst::Registry after initial registration
+        // without having to load the plugin in memory.
         klass.set_metadata(
             "RGB-GRAY Converter",
             "Filter/Effect/Converter/Video",
@@ -142,6 +151,11 @@ impl ObjectSubclass for Rgb2Gray {
             "Sebastian Dröge <sebastian@centricular.com>",
         );
 
+        // Create and add pad templates for our sink and source pad. These
+        // are later used for actually creating the pads and beforehand
+        // already provide information to GStreamer about all possible
+        // pads that could exist for this type.
+
         // On the src pad, we can produce BGRx and GRAY8 of any
         // width/height and with any framerate
         let caps = gst::Caps::new_simple(
@@ -219,8 +233,9 @@ impl ObjectSubclass for Rgb2Gray {
     }
 }
 
-// Virtual methods of GObject itself
+// Implementation of glib::Object virtual methods
 impl ObjectImpl for Rgb2Gray {
+    // This macro provides some boilerplate.
     glib_object_impl!();
 
     // Called whenever a value of a property is changed. It can be called
@@ -277,10 +292,10 @@ impl ObjectImpl for Rgb2Gray {
     }
 }
 
-// Virtual methods of gst::Element. We override none
+// Implementation of gst::Element virtual methods
 impl ElementImpl for Rgb2Gray {}
 
-// Virtual methods of gst_base::BaseTransform
+// Implementation of gst_base::BaseTransform virtual methods
 impl BaseTransformImpl for Rgb2Gray {
     // Called for converting caps from one pad to another to account for any
     // changes in the media format this element is performing.

gst-plugin-tutorial/src/sinesrc.rs

@@ -188,15 +188,20 @@ impl SineSrc {
     }
 }
 
+// This trait registers our type with the GObject object system and
+// provides the entry points for creating a new instance and setting
+// up the class data
 impl ObjectSubclass for SineSrc {
     const NAME: &'static str = "RsSineSrc";
     type ParentType = gst_base::BaseSrc;
     type Instance = gst::subclass::ElementInstanceStruct<Self>;
     type Class = subclass::simple::ClassStruct<Self>;
 
+    // This macro provides some boilerplate.
     glib_object_subclass!();
 
-    // Called when a new instance is to be created
+    // Called when a new instance is to be created. We need to return an instance
+    // of our struct here.
     fn new() -> Self {
         Self {
             cat: gst::DebugCategory::new(
@@ -224,6 +229,10 @@ impl ObjectSubclass for SineSrc {
     //
     // Our element here can output f32 and f64
     fn class_init(klass: &mut subclass::simple::ClassStruct<Self>) {
+        // Set the element specific metadata. This information is what
+        // is visible from gst-inspect-1.0 and can also be programatically
+        // retrieved from the gst::Registry after initial registration
+        // without having to load the plugin in memory.
         klass.set_metadata(
             "Sine Wave Source",
             "Source/Audio",
@@ -231,6 +240,11 @@ impl ObjectSubclass for SineSrc {
             "Sebastian Dröge <sebastian@centricular.com>",
         );
 
+        // Create and add pad templates for our sink and source pad. These
+        // are later used for actually creating the pads and beforehand
+        // already provide information to GStreamer about all possible
+        // pads that could exist for this type.
+
         // On the src pad, we can produce F32/F64 with any sample rate
         // and any number of channels
         let caps = gst::Caps::new_simple(
@@ -263,17 +277,19 @@ impl ObjectSubclass for SineSrc {
     }
 }
 
-// Virtual methods of GObject itself
+// Implementation of glib::Object virtual methods
 impl ObjectImpl for SineSrc {
+    // This macro provides some boilerplate.
     glib_object_impl!();
 
-    // Called right after construction of each object
+    // Called right after construction of a new instance
     fn constructed(&self, obj: &glib::Object) {
+        // Call the parent class' ::constructed() implementation first
         self.parent_constructed(obj);
 
-        let basesrc = obj.downcast_ref::<gst_base::BaseSrc>().unwrap();
         // Initialize live-ness and notify the base class that
         // we'd like to operate in Time format
+        let basesrc = obj.downcast_ref::<gst_base::BaseSrc>().unwrap();
         basesrc.set_live(DEFAULT_IS_LIVE);
         basesrc.set_format(gst::Format::Time);
     }
@@ -384,8 +400,11 @@ impl ObjectImpl for SineSrc {
     }
 }
 
-// Virtual methods of gst::Element. We override none
+// Implementation of gst::Element virtual methods
 impl ElementImpl for SineSrc {
+    // Called whenever the state of the element should be changed. This allows for
+    // starting up the element, allocating/deallocating resources or shutting down
+    // the element again.
     fn change_state(
         &self,
         element: &gst::Element,
@@ -401,11 +420,12 @@ impl ElementImpl for SineSrc {
             _ => (),
         }
 
+        // Call the parent class' implementation of ::change_state()
         self.parent_change_state(element, transition)
     }
 }
 
-// Virtual methods of gst_base::BaseSrc
+// Implementation of gst_base::BaseSrc virtual methods
 impl BaseSrcImpl for SineSrc {
     // Called whenever the input/output caps are changing, i.e. in the very beginning before data
     // flow happens and whenever the situation in the pipeline is changing. All buffers after this