Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Queue Javadocs #25

Merged
merged 8 commits into from

4 participants

Colin Robertson Jason Cooke [Microsoft] Joost de Nijs Louis DeJardin
Colin Robertson

Update Javadocs comments for Queue service layer code, and include package.html files.

Jason Cooke [Microsoft] jcookems commented on the diff
...azure/services/queue/models/CreateMessageOptions.java
((21 lines not shown))
*/
package com.microsoft.windowsazure.services.queue.models;
+import com.microsoft.windowsazure.services.queue.QueueContract;

Why is there a new Import?

This also shows up in some of the other files; if this is not by design the others might also need to be changed.

This import was automatically added by Eclipse whenever {@link QueueContract} was pasted into the class comments. When the import was present, then Eclipse would provide autocompletion for {@link QueueContract#...} tags elsewhere in the file. This didn't seem to be required for the Javadocs build to succeed, but I left it in because it didn't seem to harm anything and it helped for documentation comments. It's clearly a non-comment and can be removed if it's an issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jason Cooke [Microsoft] jcookems commented on the diff
...wsazure/services/queue/models/ListMessagesResult.java
((5 lines not shown))
+/**
+ * A wrapper class for the result returned from a Queue Service REST API operation to get a list of messages. This is
+ * returned by calls to implementations of {@link QueueContract#listMessages(String)} and
+ * {@link QueueContract#listMessages(String, ListMessagesOptions)}.
+ * <p>
+ * See the <a href="http://msdn.microsoft.com/en-us/library/windowsazure/dd179474.aspx">Get Messages</a> documentation

MSDN links can change. Is there an FWLink that can take users to the same place? Or someplace on the Windows Azure dev portal that links to the REST apis? (I hope there is)

This direct link style was explicitly preferred by the content editors over the creation and management of fwlinks. The links point into specific topics in the reference content directly, which are not likely to be migrated into the WindowsAzure dev portal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jason Cooke [Microsoft] jcookems commented on the diff
...owsazure/services/queue/models/ListQueuesOptions.java
((119 lines not shown))
public ListQueuesOptions setMarker(String marker) {
this.marker = marker;
return this;
}
+ /**
+ * Gets the maximum number of queues to return with a {@link QueueContract#listQueues(ListQueuesOptions) listQueues}
+ * request. If the value is not specified, the server will return up to 5,000 items.

I'm not sure how I feel about comments about the details of the service "5000 items". Those facts can change from service version to version, so by including them we make our docs implicitly tied to a version. In addition, the REST docs can have bugs of their own (perhaps they are in error and it is really 1000?), which makes comments like these even more fragile.

I agree that such specific comments on implementation details are fragile, but we also get dinged for not including the values for defaults and making them hard to find. We recently found and fixed issues in some of the Tables documents that quoted a value of 5000 that were actually supposed to be 1000, for instance. The value appears to be correct in this case, and if the implementation changes, we'll have to scour the documentation to correct it in several places anyway, so this is not adding a lot to the marginal workload.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jason Cooke [Microsoft] jcookems commented on the diff
...om/microsoft/windowsazure/services/queue/package.html
@@ -0,0 +1,5 @@
+<html>

What are these new files for?

These files are picked up by the Javadocs build and provide package-level comments. There are parallels in the services/servicebus and serviceruntime directories, and similar files need to be added for blob and table, too.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Joost de Nijs joostdenijs merged commit da5f63a into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 1, 2012
  1. Joost de Nijs

    Merge pull request #3 from WindowsAzure/dev

    joostdenijs authored
    Integrating dev branch for v0.1.3
Commits on Feb 7, 2012
  1. Joost de Nijs

    Update README.md

    joostdenijs authored
Commits on Feb 29, 2012
  1. Louis DeJardin

    Merge pull request #21 from WindowsAzure/dev

    loudej authored
    Azure SDK for Java 0.2.0 release
Commits on Mar 15, 2012
  1. Colin Robertson
Commits on Mar 19, 2012
  1. Colin Robertson
  2. Colin Robertson
  3. Colin Robertson

    Merge remote-tracking branch 'upstream/dev' into dev

    adashcolinr authored
    Conflicts:
    	README.md
Commits on Mar 22, 2012
  1. Colin Robertson
Something went wrong with that request. Please try again.