Merge pull request go-gst#97 from go-gst/remove_false_unref_docs

do not mention Unref() in the docs where not applicable

gst/app/gst_app_sink.go

@@ -40,7 +40,7 @@ var ErrEOS = errors.New("pipeline has reached end-of-stream")
 // Sink wraps an Element made with the appsink plugin with additional methods for pulling samples.
 type Sink struct{ *base.GstBaseSink }
 
-// NewAppSink returns a new appsink element. Unref after usage.
+// NewAppSink returns a new appsink element.
 func NewAppSink() (*Sink, error) {
 	elem, err := gst.NewElement("appsink")
 	if err != nil {

gst/app/gst_app_src.go

@@ -145,8 +145,6 @@ func (a *Source) PushBufferList(bufList *gst.BufferList) gst.FlowReturn {
 // push to its source pad. Any previous caps that were set on appsrc will be replaced by the caps associated with the
 // sample if not equal.
 //
-// This function does not take ownership of the sample so the sample needs to be unreffed after calling this function.
-//
 // When the block property is TRUE, this function can block until free space becomes available in the queue.
 func (a *Source) PushSample(sample *gst.Sample) gst.FlowReturn {
 	return gst.FlowReturn(C.gst_app_src_push_sample(

gst/base/gst_base_sink.go

@@ -85,7 +85,7 @@ func (g *GstBaseSink) GetDropOutOfSegment() bool {
 // GetLastSample gets the last sample that arrived in the sink and was used for preroll or for rendering.
 // This property can be used to generate thumbnails.
 //
-// The GstCaps on the sample can be used to determine the type of the buffer. Unref after usage. Sample will
+// The GstCaps on the sample can be used to determine the type of the buffer. Sample will
 // be nil if no buffer has arrived yet.
 func (g *GstBaseSink) GetLastSample() *gst.Sample {
 	sample := C.gst_base_sink_get_last_sample(g.Instance())

gst/base/gst_base_src.go

@@ -32,7 +32,7 @@ func (g *GstBaseSrc) Instance() *C.GstBaseSrc {
 	return C.toGstBaseSrc(g.Unsafe())
 }
 
-// GetAllocator retrieves the memory allocator used by this base src. Unref after usage.
+// GetAllocator retrieves the memory allocator used by this base src.
 func (g *GstBaseSrc) GetAllocator() (*gst.Allocator, *gst.AllocationParams) {
 	var allocParams C.GstAllocationParams
 	var allocator *C.GstAllocator
@@ -46,7 +46,7 @@ func (g *GstBaseSrc) GetAllocator() (*gst.Allocator, *gst.AllocationParams) {
 // GetBlocksize returns the number of bytes that the source will push out with each buffer.
 func (g *GstBaseSrc) GetBlocksize() uint { return uint(C.gst_base_src_get_blocksize(g.Instance())) }
 
-// GetBufferPool returns the BufferPool used by this source. Unref after usage.
+// GetBufferPool returns the BufferPool used by this source.
 func (g *GstBaseSrc) GetBufferPool() *gst.BufferPool {
 	pool := C.gst_base_src_get_buffer_pool(g.Instance())
 	if pool == nil {

gst/base/gst_base_transform.go

@@ -52,7 +52,7 @@ func (g *GstBaseTransform) Instance() *C.GstBaseTransform {
 	return C.toGstBaseTransform(g.Unsafe())
 }
 
-// GetAllocator retrieves the memory allocator used by this base transform. Unref after usage.
+// GetAllocator retrieves the memory allocator used by this base transform.
 func (g *GstBaseTransform) GetAllocator() (*gst.Allocator, *gst.AllocationParams) {
 	var allocParams C.GstAllocationParams
 	var allocator *C.GstAllocator
@@ -63,7 +63,7 @@ func (g *GstBaseTransform) GetAllocator() (*gst.Allocator, *gst.AllocationParams
 	return gst.FromGstAllocatorUnsafeFull(unsafe.Pointer(allocator)), gst.FromGstAllocationParamsUnsafe(unsafe.Pointer(&allocParams))
 }
 
-// GetBufferPool returns the BufferPool used by this transform. Unref after usage.
+// GetBufferPool returns the BufferPool used by this transform.
 func (g *GstBaseTransform) GetBufferPool() *gst.BufferPool {
 	pool := C.gst_base_transform_get_buffer_pool(g.Instance())
 	if pool == nil {

gst/base/gst_type_find.go

@@ -14,7 +14,7 @@ import (
 )
 
 // TypeFindHelper tries to find what type of data is flowing from the given source GstPad.
-// Returns nil if no Caps matches the data stream. Unref after usage.
+// Returns nil if no Caps matches the data stream.
 func TypeFindHelper(pad *gst.Pad, size uint64) *gst.Caps {
 	caps := C.gst_type_find_helper((*C.GstPad)(unsafe.Pointer(pad.Instance())), C.guint64(size))
 	if caps == nil {
@@ -32,8 +32,7 @@ func TypeFindHelper(pad *gst.Pad, size uint64) *gst.Caps {
 // the caps with the highest probability will be returned, or nil if the content of the buffer could
 // not be identified.
 //
-// Object can either be nil or the object doing the typefinding (used for logging). Caps should be unrefed
-// after usage.
+// Object can either be nil or the object doing the typefinding (used for logging).
 func TypeFindHelperForBuffer(obj *gst.Object, buffer *gst.Buffer) (*gst.Caps, gst.TypeFindProbability) {
 	var prob C.GstTypeFindProbability
 	var cobj *C.GstObject
@@ -57,8 +56,6 @@ func TypeFindHelperForBuffer(obj *gst.Object, buffer *gst.Buffer) (*gst.Caps, gs
 //
 // When extension is not empty, this function will first try the typefind functions for the given extension,
 // which might speed up the typefinding in many cases.
-//
-// Unref caps after usage.
 func TypeFindHelperForBufferWithExtension(obj *gst.Object, buffer *gst.Buffer, extension string) (*gst.Caps, gst.TypeFindProbability) {
 	var prob C.GstTypeFindProbability
 	var cobj *C.GstObject
@@ -87,8 +84,7 @@ func TypeFindHelperForBufferWithExtension(obj *gst.Object, buffer *gst.Buffer, e
 // the caps with the highest probability will be returned, or nil if the content of the buffer could
 // not be identified.
 //
-// Object can either be nil or the object doing the typefinding (used for logging). Caps should be unrefed
-// after usage.
+// Object can either be nil or the object doing the typefinding (used for logging).
 func TypeFindHelperForData(obj *gst.Object, data []byte) (*gst.Caps, gst.TypeFindProbability) {
 	var prob C.GstTypeFindProbability
 	var cobj *C.GstObject
@@ -113,7 +109,7 @@ func TypeFindHelperForData(obj *gst.Object, data []byte) (*gst.Caps, gst.TypeFin
 // When extension is not empty, this function will first try the typefind functions for the given extension,
 // which might speed up the typefinding in many cases.
 //
-// Object can either be nil or the object doing the typefinding (used for logging). Unref caps after usage.
+// Object can either be nil or the object doing the typefinding (used for logging).
 func TypeFindHelperForDataWithExtension(obj *gst.Object, data []byte, extension string) (*gst.Caps, gst.TypeFindProbability) {
 	var prob C.GstTypeFindProbability
 	var cobj *C.GstObject
@@ -138,7 +134,7 @@ func TypeFindHelperForDataWithExtension(obj *gst.Object, data []byte, extension
 // All available typefinders will be checked against the extension in order of rank. The caps of the first typefinder
 // that can handle extension will be returned.
 //
-// Object can either be nil or the object doing the typefinding (used for logging). Unref caps after usage.
+// Object can either be nil or the object doing the typefinding (used for logging).
 func TypeFindHelperForExtension(obj *gst.Object, extension string) *gst.Caps {
 	var cobj *C.GstObject
 	if obj != nil {

gst/gst_bin.go

@@ -122,7 +122,7 @@ func ToGstBin(obj interface{}) *Bin {
 // Instance returns the underlying GstBin instance.
 func (b *Bin) Instance() *C.GstBin { return C.toGstBin(b.Unsafe()) }
 
-// GetElementByName returns the element with the given name. Unref after usage.
+// GetElementByName returns the element with the given name.
 func (b *Bin) GetElementByName(name string) (*Element, error) {
 	cName := C.CString(name)
 	defer C.free(unsafe.Pointer(cName))
@@ -134,7 +134,7 @@ func (b *Bin) GetElementByName(name string) (*Element, error) {
 }
 
 // GetElementByNameRecursive returns the element with the given name. If it is not
-// found in this Bin, parent Bins are searched recursively. Unref after usage.
+// found in this Bin, parent Bins are searched recursively.
 func (b *Bin) GetElementByNameRecursive(name string) (*Element, error) {
 	cName := C.CString(name)
 	defer C.free(unsafe.Pointer(cName))
@@ -164,8 +164,7 @@ func (b *Bin) GetSourceElements() ([]*Element, error) {
 	return iteratorToElementSlice(iterator)
 }
 
-// GetSinkElements returns a list of all the sink elements in this Bin. Unref
-// elements after usage.
+// GetSinkElements returns a list of all the sink elements in this Bin.
 func (b *Bin) GetSinkElements() ([]*Element, error) {
 	iterator := C.gst_bin_iterate_sinks((*C.GstBin)(b.Instance()))
 	return iteratorToElementSlice(iterator)
@@ -192,7 +191,6 @@ func (b *Bin) GetByInterface(iface glib.Interface) (*Element, error) {
 
 // GetAllByInterface looks for all elements inside the bin that implements the given interface. You can
 // safely cast all returned elements to the given interface. The function recurses inside child bins.
-// The function will return a series of Elements that should be unreffed after use.
 func (b *Bin) GetAllByInterface(iface glib.Interface) ([]*Element, error) {
 	iterator := C.gst_bin_iterate_all_by_interface(b.Instance(), C.GType(iface.Type()))
 	return iteratorToElementSlice(iterator)
@@ -244,8 +242,7 @@ func (b *Bin) RemoveMany(elems ...*Element) error {
 }
 
 // FindUnlinkedPad recursively looks for elements with an unlinked pad of the given direction
-// within this bin and returns an unlinked pad if one is found, or NULL otherwise. If a pad is
-// found, the caller owns a reference to it and should unref it when it is not needed any longer.
+// within this bin and returns an unlinked pad if one is found, or NULL otherwise.
 func (b *Bin) FindUnlinkedPad(direction PadDirection) *Pad {
 	pad := C.gst_bin_find_unlinked_pad(b.Instance(), C.GstPadDirection(direction))
 	if pad == nil {

gst/gst_buffer.go

@@ -126,16 +126,11 @@ func NewBufferFromReader(rdr io.Reader) (*Buffer, error) {
 //
 // The prefix/padding must be filled with 0 if flags contains MemoryFlagZeroPrefixed and MemoryFlagZeroPadded respectively.
 //
-//	 // Example
-//
-//	 buf := gst.NewBufferFull(0, []byte("hello-world"), 1024, 0, 1024, func() {
-//	     fmt.Println("buffer was destroyed")
-//	 })
-//	 if buf != nil {
-//	     buf.Unref()
-//	 }
+//	// Example
 //
-//	// > buffer was destroyed
+//	buf := gst.NewBufferFull(0, []byte("hello-world"), 1024, 0, 1024, func() {
+//	    fmt.Println("buffer was destroyed")
+//	})
 func NewBufferFull(flags MemoryFlags, data []byte, maxSize, offset, size int64, notifyFunc func()) *Buffer {
 	var notifyData unsafe.Pointer
 	var gnotifyFunc C.GDestroyNotify
@@ -244,8 +239,6 @@ func (b *Buffer) OffsetEnd() int64 { return int64(b.Instance().offset_end) }
 //	buf := gst.NewEmptyBuffer()
 //	buf.AddMeta(metaInfo, "hello world")
 //
-//	buf.Unref()
-//
 //	// > Buffer initialized with params: hello world
 //	// > Buffer was destroyed
 func (b *Buffer) AddMeta(info *MetaInfo, params interface{}) *Meta {

gst/gst_bus.go

@@ -49,18 +49,15 @@ type Bus struct {
 //	    gst.Init(nil)
 //
 //	    bus := gst.NewBus()
-//	    defer bus.Unref()
 //
 //	    elem, err := gst.NewElement("fakesrc")
 //	    if err != nil {
 //	        panic(err)
 //	    }
-//	    defer elem.Unref()
 //
 //	    bus.Post(gst.NewAsyncStartMessage(elem))
 //
 //	    msg := bus.Pop()
-//	    defer msg.Unref()
 //
 //	    fmt.Println(msg)
 //	}
@@ -92,7 +89,6 @@ func (b *Bus) Instance() *C.GstBus { return C.toGstBus(b.Unsafe()) }
 func (b *Bus) AddSignalWatch() { C.gst_bus_add_signal_watch(b.Instance()) }
 
 // PopMessage attempts to pop a message from the bus. It returns nil if none are available.
-// The message should be unreffed after usage.
 //
 // It is much safer and easier to use the AddWatch or other polling functions. Only use this method if you
 // are unable to also run a MainLoop, or for convenience sake.
@@ -101,8 +97,7 @@ func (b *Bus) PopMessage(timeout ClockTime) *Message {
 }
 
 // BlockPopMessage blocks until a message is available on the bus and then returns it.
-// This function can return nil if the bus is closed. The message should be unreffed
-// after usage.
+// This function can return nil if the bus is closed.
 //
 // It is much safer and easier to use the AddWatch or other polling functions. Only use this method if you
 // are unable to also run a MainLoop, or for convenience sake.
@@ -120,15 +115,12 @@ func (b *Bus) BlockPopMessage() *Message {
 }
 
 // BusWatchFunc is a go representation of a GstBusFunc. It takes a message as a single argument
-// and returns a bool value for whether to continue processing messages or not. There is no need to unref
-// the message unless additional references are placed on it during processing.
+// and returns a bool value for whether to continue processing messages or not.
 type BusWatchFunc func(msg *Message) bool
 
 // AddWatch adds a watch to the default MainContext for messages emitted on this bus.
 // This function is used to receive asynchronous messages in the main loop. There can
 // only be a single bus watch per bus, you must remove it before you can set a new one.
-// It is safe to unref the Bus after setting this watch, since the watch itself will take
-// it's own reference to the Bus.
 //
 // The watch can be removed either by returning false from the function or by using RemoveWatch().
 // A MainLoop must be running for bus watches to work.
@@ -217,7 +209,7 @@ func (b *Bus) HavePending() bool {
 }
 
 // Peek peeks the message on the top of the bus' queue. The message will remain on the bus'
-// message queue. A reference is returned, and needs to be unreffed by the caller.
+// message queue.
 func (b *Bus) Peek() *Message {
 	msg := C.gst_bus_peek(b.Instance())
 	if msg == nil {
@@ -312,7 +304,7 @@ func (b *Bus) SetSyncHandler(f BusSyncHandler) {
 	)
 }
 
-// TimedPop gets a message from the bus, waiting up to the specified timeout. Unref returned messages after usage.
+// TimedPop gets a message from the bus, waiting up to the specified timeout.
 //
 // If timeout is 0, this function behaves like Pop. If timeout is ClockTimeNone, this function will block forever until a message was posted on the bus.
 func (b *Bus) TimedPop(dur ClockTime) *Message {

gst/gst_caps.go

@@ -185,10 +185,7 @@ func (c *Caps) CanIntersect(caps *Caps) bool {
 // Copy creates a new Caps as a copy of these. The new caps will have a refcount of 1, owned by the caller.
 // The structures are copied as well.
 //
-// Note that this function is the semantic equivalent of a Ref followed by a MakeWritable. If you only want to hold
-// on to a reference to the data, you should use Ref.
-//
-// When you are finished with the caps, call Unref on it.
+// Note that this function is the semantic equivalent of a Ref followed by a MakeWritable.
 func (c *Caps) Copy() *Caps {
 	return FromGstCapsUnsafeFull(unsafe.Pointer(C.gst_caps_copy(c.Instance())))
 }

gst/gst_child_proxy.go

@@ -137,7 +137,7 @@ func (c *ChildProxy) Get(names ...string) []*glib.Value {
 }
 
 // GetChildByIndex fetches a child by its number. This function can return nil if the object is not
-// found. Unref after usage.
+// found.
 func (c *ChildProxy) GetChildByIndex(idx uint) *glib.Object {
 	gobj := C.gst_child_proxy_get_child_by_index(c.Instance(), C.guint(idx))
 	if gobj == nil {
@@ -150,7 +150,7 @@ func (c *ChildProxy) GetChildByIndex(idx uint) *glib.Object {
 // together with Object.GetName. If the interface is to be used with GObjects, this method needs
 // to be overridden.
 //
-// This function can return nil if the object is not found. Unref after usage.
+// This function can return nil if the object is not found.
 func (c *ChildProxy) GetChildByName(name string) *glib.Object {
 	cname := C.CString(name)
 	defer C.free(unsafe.Pointer(cname))
@@ -182,7 +182,6 @@ func (c *ChildProxy) GetProperty(name string) *glib.Value {
 
 // Lookup looks up which object and and parameter would be affected by the given name.
 // If ok is false, the targets could not be found and this function returned nil.
-// Unref target after usage.
 func (c *ChildProxy) Lookup(name string) (ok bool, target *glib.Object, param *glib.ParamSpec) {
 	var gtarget *C.GObject
 	var gspec *C.GParamSpec

gst/gst_clock.go

@@ -116,7 +116,6 @@ func (c *ClockID) Wait() (ret ClockReturn, jitter ClockTimeDiff) {
 //	// Example
 //
 //	pipeline, _ := gst.NewPipelineFromString("fakesrc ! fakesink")
-//	defer pipeline.Unref()
 //
 //	clock := pipeline.GetPipelineClock()
 //
@@ -276,7 +275,7 @@ func (c *Clock) GetTimeout() ClockTime {
 func (c *Clock) IsSynced() bool { return gobool(C.gst_clock_is_synced(c.Instance())) }
 
 // NewPeriodicID gets an ID from clock to trigger a periodic notification. The periodic notifications
-// will start at time start_time and will then be fired with the given interval. ID should be unreffed after usage.
+// will start at time start_time and will then be fired with the given interval.
 func (c *Clock) NewPeriodicID(startTime, interval ClockTime) *ClockID {
 	id := C.gst_clock_new_periodic_id(
 		c.Instance(),
@@ -289,7 +288,6 @@ func (c *Clock) NewPeriodicID(startTime, interval ClockTime) *ClockID {
 }
 
 // NewSingleShotID gets a ClockID from the clock to trigger a single shot notification at the requested time.
-// The single shot id should be unreffed after usage.
 func (c *Clock) NewSingleShotID(at ClockTime) *ClockID {
 	id := C.gst_clock_new_single_shot_id(
 		c.Instance(),

gst/gst_device.go

@@ -42,7 +42,7 @@ func (d *Device) CreateElement(name string) *Element {
 	return FromGstElementUnsafeNone(unsafe.Pointer(elem))
 }
 
-// GetCaps returns the caps that this device supports. Unref after usage.
+// GetCaps returns the caps that this device supports.
 func (d *Device) GetCaps() *Caps {
 	caps := C.gst_device_get_caps(d.Instance())
 	if caps == nil {

gst/gst_element_class.go

@@ -72,7 +72,7 @@ func (e *ElementClass) GetMetadata(key string) string {
 	return C.GoString(C.gst_element_class_get_metadata(e.Instance(), (*C.gchar)(ckey)))
 }
 
-// GetPadTemplate retrieves the padtemplate with the given name. No unrefing is necessary.
+// GetPadTemplate retrieves the padtemplate with the given name.
 // If no pad template exists with the given name, nil is returned.
 func (e *ElementClass) GetPadTemplate(name string) *PadTemplate {
 	cname := C.CString(name)

gst/gst_element_factory.go

@@ -93,7 +93,7 @@ func NewElementMany(elemNames ...string) ([]*Element, error) {
 // ElementFactory wraps the GstElementFactory
 type ElementFactory struct{ *PluginFeature }
 
-// Find returns the factory for the given plugin, or nil if it doesn't exist. Unref after usage.
+// Find returns the factory for the given plugin, or nil if it doesn't exist.
 func Find(name string) *ElementFactory {
 	cName := C.CString(name)
 	defer C.free(unsafe.Pointer(cName))

gst/gst_ghost_pad.go

@@ -161,7 +161,7 @@ func (p *ProxyPad) toPad() *C.GstPad { return C.toGstPad(p.Unsafe()) }
 // Instance returns the underlying GstProxyPad instance.
 func (p *ProxyPad) Instance() *C.GstProxyPad { return C.toGstProxyPad(p.Unsafe()) }
 
-// GetInternal gets the internal pad of pad. Unref target pad after usage.
+// GetInternal gets the internal pad of pad.
 //
 // The internal pad of a GhostPad is the internally used pad of opposite direction, which is used to link to the target.
 func (p *ProxyPad) GetInternal() *ProxyPad {