Merge pull request #1516 from apache/tristan/source-set-ref
source.py: Document Source.set_ref() properly
diff --git a/src/buildstream/source.py b/src/buildstream/source.py
index bd4b3ec..fa8042c 100644
--- a/src/buildstream/source.py
+++ b/src/buildstream/source.py
@@ -414,13 +414,29 @@
node: The same dictionary which was previously passed
to :func:`Plugin.configure() <buildstream.plugin.Plugin.configure>`
- See :func:`Source.get_ref() <buildstream.source.Source.get_ref>`
- for a discussion on the *ref* parameter.
+ The implementor must update the *node* parameter to reflect the new *ref*,
+ and it should store the passed *ref* so that it will be returned in any
+ later calls to :func:`Source.get_ref() <buildstream.source.Source.get_ref>`.
- .. note::
+ The passed *ref* parameter is guaranteed to either be a value which has
+ been previously retrieved by the :func:`Source.get_ref() <buildstream.source.Source.get_ref>`
+ method on the same plugin, or ``None``.
- Implementors must support the special ``None`` value here to
- allow clearing any existing ref.
+ **Example:**
+
+ .. code:: python
+
+ # Implementation of Source.set_ref()
+ #
+ def set_ref(self, ref, node):
+
+ # Update internal state of the ref
+ self.ref = ref
+
+ # Update the passed node so that we will read the new ref
+ # next time this source plugin is configured with this node.
+ #
+ node["ref"] = self.ref
"""
raise ImplError("Source plugin '{}' does not implement set_ref()".format(self.get_kind()))
