Docs for classes in apollo-api module #444

VisheshVadhera · 2017-04-21T19:16:24Z

Closes #435

VisheshVadhera · 2017-04-21T19:17:45Z

apollo-api/src/main/java/com/apollographql/apollo/api/Field.java

@@ -254,6 +382,9 @@ public ScalarType scalarType() {
    }
  }

+  /**
+   * Abstraction for a Field representing a conditional type.
+   */
  public static final class ConditionalTypeField extends Field {


I feel docs can certainly be improved for ConditionalType. Can you suggest better docs here?

Conditional Type used for parsing inline fragments or fragments. Here is an example how it used:

final Field[] fields = { Field.forConditionalType("__typename", "__typename", new Field.ConditionalTypeReader<Fragments>() { @Override public Fragments read(String conditionalType, ResponseReader reader) throws IOException { return fragmentsFieldMapper.map(reader, conditionalType); } }) };

It means that first field __typename will be read and then passed to another nested mapper along with reader that will decide by checking conditionalType what type of fragment it will parse.

sav007 · 2017-04-21T23:13:23Z

apollo-api/src/main/java/com/apollographql/apollo/api/Field.java

+ *
+ * Field can refer to: <b>GraphQL Scalar Types, Objects or List</b>. For a complete list of types that a Field
+ * object can refer to see {@link Field.Type} class.
+ */
 public class Field {


I feel like this class should be moved under internal package as it used internally by generated mappers

sav007 · 2017-04-21T23:14:08Z

apollo-api/src/main/java/com/apollographql/apollo/api/ScalarType.java

@@ -1,5 +1,8 @@
 package com.apollographql.apollo.api;

+/**
+ * Represents a custom graphQL scalar type


sav007 · 2017-04-21T23:15:23Z

apollo-api/src/main/java/com/apollographql/apollo/api/ResponseReader.java

-/** TODO **/
+/*
+ * ResponseReader is responsible for converting a field object to another object of type T.
+ */


I would change this to: ResponseReader is an abstraction for reading GraphQL fields.

sav007 · 2017-04-21T23:17:23Z

apollo-api/src/main/java/com/apollographql/apollo/api/ResponseFieldMapper.java

@@ -2,7 +2,9 @@

 import java.io.IOException;

-/** TODO */
+/**
+ * * ResponseFieldMapper is responsible for mapping the responses returned by the server back to data.


one * is redundant.

ResponseFieldMapper is an abstraction for mapping the response data returned by the server back to generated models.

sav007 · 2017-04-21T23:18:15Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

  String queryDocument();

-  /** TODO */
+  /**
+   * Returns the Variable object associated with this GraphQL operation.


Returns the variables associated with this GraphQL operation.

sav007 · 2017-04-21T23:18:22Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

 public interface Operation<D extends Operation.Data, T, V extends Operation.Variables> {
-  /** TODO */
+  /**
+   * Returns the raw graphQL operation string.


sav007 · 2017-04-21T23:19:25Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

  V variables();

+  /**
+   * Returns a mapper that maps the server response back to an object of type D.


Returns a mapper that maps the server response data to generated model data class {link D}

sav007 · 2017-04-21T23:20:56Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

  ResponseFieldMapper<D> responseFieldMapper();

+  /**
+   * Converts the object representing the server response to another type.


Wraps generated response data class {link D} with another class, example Optional.fromNullable(data)

sav007 · 2017-04-21T23:22:49Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

-  /** TODO */
+  /**
+   * Abstraction for the variables which are a part of the GraphQL operation. For example, for the following GraphQL
+   * operation, Variables represents an abstraction for GraphQL variables '$type' and '$limit' their values:


... variables represents values for GraphQL '$type' and '$limit' variables:

… feature-apollo-api-docs

VisheshVadhera · 2017-04-22T06:09:14Z

@sav007 Made the requested set of changes. If everything looks fine, we can go ahead and merge it.

sav007 · 2017-04-23T04:08:37Z

apollo-api/src/main/java/com/apollographql/apollo/api/ResponseReader.java

 public interface ResponseReader {
-  <T> T read(Field field) throws IOException;
+  <T> T read(com.apollographql.apollo.api.internal.Field field) throws IOException;


missing import

Ah! Totally missed that.

sav007

lgtm, small comment
@digitalbuddha @marwanad fresh look at this PR

marwanad · 2017-04-23T04:43:20Z

apollo-api/src/main/java/com/apollographql/apollo/api/Error.java

  public String message() {
    return message;
  }

+  /**
+   * Returns the location of the error in the query.


operation instead of query? (To cover mutation cases too)

marwanad · 2017-04-23T04:44:54Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

@@ -5,28 +5,60 @@

 import javax.annotation.Nonnull;

-/** TODO */
+/**
+ * Operation represents an abstraction for a GraphQL operation (mutation or query).


Can remove Operation to keep it consistent with he doc for Mutation

VisheshVadhera · 2017-04-24T02:38:49Z

@sav007 @marwanad Have made the requested set of changes. If it looks fine, we can merge it.

digitalbuddha · 2017-04-24T14:16:23Z

apollo-api/src/main/java/com/apollographql/apollo/api/Error.java

@@ -15,10 +17,16 @@ public Error(String message, @Nullable List<Location> locations) {
    this.locations = locations;
  }

+  /**
+   * Returns the error message returned by the server.


Returns server error message.

digitalbuddha · 2017-04-24T14:17:11Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

 public interface Operation<D extends Operation.Data, T, V extends Operation.Variables> {
-  /** TODO */
+  /**
+   * Returns the raw GraphQL operation string.


nitpick String

digitalbuddha · 2017-04-24T14:18:41Z

apollo-api/src/main/java/com/apollographql/apollo/api/Operation.java

  class Variables {
    protected Variables() {
    }

-    @Nonnull protected Map<String, Object> valueMap() {
+    @Nonnull public Map<String, Object> valueMap() {


why did this change to public?

We moved the Field class to the internal package (which was earlier in the same package as the Operation interface) and Field class was using valueMap method. Hence it had to be changed to public.

digitalbuddha · 2017-04-24T14:20:25Z

apollo-api/src/main/java/com/apollographql/apollo/api/Query.java

@@ -1,5 +1,7 @@
 package com.apollographql.apollo.api;

-/** TODO */
+/**
+ * Represents an abstraction for GraphQL query that will be sent to the server.


I personally prefer comments like Represents a custom GraphQL scalar type rather than things that mention something is an abstraction. So this one I think sounds better as "Represents a GraphQL query that will be sent to a server"

digitalbuddha

small nitpicks :-)

… feature-apollo-api-docs

VisheshVadhera · 2017-04-27T16:49:03Z

@sav007 Tests in the CodegenTest.kt class are failing due to moving the Field class to the internal package. Any idea how this can be fixed? Don't have much experience with Kotlin.

sav007 · 2017-04-27T16:57:07Z

@VisheshVadhera I am so sorry but with latest custom resolver feature, we no longer need to hide Field in internal package, could you please revert it back. Sorry.

… feature-apollo-api-docs

VisheshVadhera · 2017-04-27T17:48:37Z

@sav007 Reverted :)

sav007 · 2017-04-27T18:32:27Z

Merging

VisheshVadhera added 4 commits April 21, 2017 16:47

Add rough docs for all api classes

290f782

Second draft of the docs

3f052cb

Docs for error & field

ac6f407

Add docs for the remaining interfaces

cb8733e

VisheshVadhera commented Apr 21, 2017

View reviewed changes

VisheshVadhera changed the title ~~Feature apollo api docs~~ Docs for classes in apollo-api module Apr 21, 2017

sav007 reviewed Apr 21, 2017

View reviewed changes

VisheshVadhera added 2 commits April 22, 2017 11:35

Code review

f6b1f28

Merge branch 'master' of github.com:apollographql/apollo-android into…

7f71e8d

… feature-apollo-api-docs

sav007 reviewed Apr 23, 2017

View reviewed changes

sav007 approved these changes Apr 23, 2017

View reviewed changes

marwanad reviewed Apr 23, 2017

View reviewed changes

VisheshVadhera added 2 commits April 23, 2017 12:26

Code review

4036c4c

Fix import

5e02011

digitalbuddha reviewed Apr 24, 2017

View reviewed changes

digitalbuddha approved these changes Apr 24, 2017

View reviewed changes

VisheshVadhera added 3 commits April 24, 2017 20:17

Code review

acce4f8

Merge branch 'master' of github.com:apollographql/apollo-android into…

3dad214

… feature-apollo-api-docs

Merge branch 'master' of github.com:apollographql/apollo-android into…

67e9541

… feature-apollo-api-docs

VisheshVadhera added 2 commits April 27, 2017 23:12

Revert the package change

ecf7463

Merge branch 'master' of github.com:apollographql/apollo-android into…

60e2e2c

… feature-apollo-api-docs

sav007 merged commit 65c4fff into apollographql:master Apr 27, 2017

VisheshVadhera deleted the feature-apollo-api-docs branch May 13, 2017 10:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs for classes in apollo-api module #444

Docs for classes in apollo-api module #444

VisheshVadhera commented Apr 21, 2017

VisheshVadhera Apr 21, 2017 •

edited

Loading

sav007 Apr 21, 2017

sav007 Apr 21, 2017

sav007 Apr 21, 2017

sav007 Apr 21, 2017

sav007 Apr 21, 2017

sav007 Apr 21, 2017

sav007 Apr 21, 2017

sav007 Apr 21, 2017 •

edited

Loading

sav007 Apr 21, 2017

sav007 Apr 21, 2017

VisheshVadhera commented Apr 22, 2017

sav007 Apr 23, 2017

VisheshVadhera Apr 23, 2017

sav007 left a comment

marwanad Apr 23, 2017

VisheshVadhera Apr 23, 2017

marwanad Apr 23, 2017

VisheshVadhera commented Apr 24, 2017

digitalbuddha Apr 24, 2017

digitalbuddha Apr 24, 2017

digitalbuddha Apr 24, 2017

VisheshVadhera Apr 24, 2017

digitalbuddha Apr 24, 2017

digitalbuddha left a comment

VisheshVadhera commented Apr 27, 2017 •

edited

Loading

sav007 commented Apr 27, 2017

VisheshVadhera commented Apr 27, 2017

sav007 commented Apr 27, 2017

Docs for classes in apollo-api module #444

Docs for classes in apollo-api module #444

Conversation

VisheshVadhera commented Apr 21, 2017

VisheshVadhera Apr 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sav007 Apr 21, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VisheshVadhera commented Apr 22, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sav007 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VisheshVadhera commented Apr 24, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

digitalbuddha left a comment

Choose a reason for hiding this comment

VisheshVadhera commented Apr 27, 2017 • edited Loading

sav007 commented Apr 27, 2017

VisheshVadhera commented Apr 27, 2017

sav007 commented Apr 27, 2017

VisheshVadhera Apr 21, 2017 •

edited

Loading

sav007 Apr 21, 2017 •

edited

Loading

VisheshVadhera commented Apr 27, 2017 •

edited

Loading