launchpad-reviewers team mailing list archive

[John A Meinel <john@xxxxxxxxxxxxxxxxx>]

John A Meinel has proposed merging lp:~jameinel/maas/maascli-tag-help into lp:maas.

Commit message:
Add documentation to the various Tag apis.

Some APIs were still describing themselves as 'Nodes', these have been fixed to say 'Tags'. Other ones were updated to describe the list of possible parameters that could be passed to the API.

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)
Related bugs:
  Bug #1064735 in MAAS: "maas-cli tag commands needs help "
  https://bugs.launchpad.net/maas/+bug/1064735

For more details, see:
https://code.launchpad.net/~jameinel/maas/maascli-tag-help/+merge/128879
-- 
https://code.launchpad.net/~jameinel/maas/maascli-tag-help/+merge/128879
Your team Launchpad code reviewers is requested to review the proposed merge of lp:~jameinel/maas/maascli-tag-help into lp:maas.

=== modified file 'src/maasserver/api.py'
--- src/maasserver/api.py	2012-10-09 11:23:56 +0000
+++ src/maasserver/api.py	2012-10-10 08:33:18 +0000
@@ -1381,11 +1381,18 @@
         )
 
     def read(self, request, name):
-        """Read a specific Node."""
+        """Read a specific Tag"""
         return Tag.objects.get_tag_or_404(name=name, user=request.user)
 
     def update(self, request, name):
-        """Update a specific `Tag`.
+        """Update a specific Tag.
+
+        :param name: The name of the Tag to be created. This should be a short
+            name, and will be used in the URL of the tag.
+        :param comment: A long form description of what the tag is meant for.
+            It is meant as a human readable description of the tag.
+        :param definition: An XPATH query that will be evaluated against the
+            hardware_details stored for all nodes (output of `lshw -xml`).
         """
         tag = Tag.objects.get_tag_or_404(name=name, user=request.user,
             to_edit=True)
@@ -1404,7 +1411,7 @@
             raise ValidationError(form.errors)
 
     def delete(self, request, name):
-        """Delete a specific Node."""
+        """Delete a specific Tag."""
         tag = Tag.objects.get_tag_or_404(name=name,
             user=request.user, to_edit=True)
         tag.delete()
@@ -1427,7 +1434,12 @@
 
     @operation(idempotent=False)
     def rebuild(self, request, name):
-        """Trigger rebuilding the tag <=> node mapping."""
+        """Manually trigger a rebuild the tag <=> node mapping.
+
+        This is considered a maintenance operation, which should normally not
+        be necessary. Adding nodes or updating a tag's definition should
+        automatically trigger the appropriate changes.
+        """
         tag = Tag.objects.get_tag_or_404(name=name, user=request.user,
                                          to_edit=True)
         tag.populate_nodes()
@@ -1478,7 +1490,14 @@
 
     @operation(idempotent=False)
     def new(self, request):
-        """Create a new `Tag`.
+        """Create a new Tag.
+
+        :param name: The name of the Tag to be created. This should be a short
+            name, and will be used in the URL of the tag.
+        :param comment: A long form description of what the tag is meant for.
+            It is meant as a human readable description of the tag.
+        :param definition: An XPATH query that will be evaluated against the
+            hardware_details stored for all nodes (output of `lshw -xml`).
         """
         if not request.user.is_superuser:
             raise PermissionDenied()
@@ -1491,6 +1510,8 @@
     @operation(idempotent=True)
     def list(self, request):
         """List Tags.
+
+        Get a listing of all tags that are currently defined.
         """
         return Tag.objects.all()