Godoc front page #78

eginez · 2018-02-14T20:17:11Z

This PR adds content to the front page of the godocs page. It covers applicable technical information including: Optional fields, Signer, Pagination, Logging, Polymorphic json, etc. It also includes a brief example on how to get started with SDK, otherwise it references the examples directory or the readme file

jodoglevy · 2018-02-22T06:59:09Z

oci.go

+The SDK uses pointers for primitive types in many input structs. To aid in the construction of such structs, the SDK provides
+functions that returns a pointer for a given value. For example:
+
+	//Given the struct


other comments above you put a space after the // before the comment

jodoglevy · 2018-02-22T07:01:36Z

oci.go

+
+		DisplayName *string `mandatory:"false" json:"displayName"`
+
+		DisplayNumber *int `mandatory:"false" json:"dnsNumber"`


whats a DisplayNumber? Why isn't this dnsNumber?

also, does create vcn really take a dnsNumber param? seems wrong

jodoglevy · 2018-02-22T07:02:41Z

oci.go

+		DisplayNumber *int `mandatory:"false" json:"dnsNumber"`
+	}
+
+	//We can use the helper functions to build the struct


same comment re // space

jodoglevy · 2018-02-22T07:03:48Z

oci.go

+
+Signing custom requests
+
+The oci-go-sdk exposes a stand-alone signer that can be used to sign custom requests. For example:


you call it 'sdk' in other places, but oci-go-sdk here. should be consistent

is there a way to link to the signer's entry in the api ref here as well?

jodoglevy · 2018-02-22T07:05:46Z

oci.go

+	var request http.Request
+	request = ... // some custom request
+
+	//Mandatory headers to be used in the sign process


same point re // space here and below comments

" sign process" -> " signing process"

jodoglevy · 2018-02-22T07:07:36Z

oci.go

+	// A predicate that specifies when to use the optional signing headers
+	optionalHeadersPredicate := func (r *http.Request) bool {
+		return r.Method == http.MethodPost
 	}


why make the user pass this? this is common to OCI signing logic and wouldn't change based on user's code:

defaultGenericHeaders = []string{"date", "(request-target)", "host"} //Optional headers optionalHeaders = []string{"content-length", "content-type", "x-content-sha256"} // A predicate that specifies when to use the optional signing headers optionalHeadersPredicate := func (r *http.Request) bool { return r.Method == http.MethodPost }

jodoglevy · 2018-02-22T07:09:28Z

oci.go

+	//Build the signer
+	signer := common.RequestSigner(provider, defaultGenericHeaders, optionalHeaders, optionalHeadersPredicate)
+
+	//Signs the request


based on other tenses in comments, this should be 'Sign the request'

jodoglevy · 2018-02-22T07:10:11Z

oci.go

+
+	//Signs the request
+	signer.Sign(&request)
+


i think the example should show making the request, once its signed, too?

jodoglevy · 2018-02-22T07:11:14Z

oci.go

+	//Signs the request
+	signer.Sign(&request)
+
+For more information on the signing algorithm refer to:  https://tools.ietf.org/html/draft-cavage-http-signatures-08


please link to https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/signingrequests.htm instead. it does link to this link you've provided for more info if user needs it, but the TC doc is much more grokable than the spec itself.

jodoglevy · 2018-02-22T07:11:58Z

oci.go

+
+Polymorphic json requests and responses
+
+Some operations accept or return polymorphic json objects. The SDK models such objects as an interface. Further the SDK provides


"The SDK models such objects as an interface" -> "The SDK models such objects as interfaces"

jodoglevy · 2018-02-22T07:12:55Z

oci.go

-	fmt.Println("Group's name is:", response.Name)

-Organization of the SDK
+	// The CreateIdentityProviderRequest. Takes a CreateIdentityProviderDetails interface as input


stray period

or maybe not. nevermind

jodoglevy · 2018-02-22T07:14:01Z

oci.go

+	// The CreateIdentityProviderRequest. Takes a CreateIdentityProviderDetails interface as input
+	rCreate := identity.CreateIdentityProviderRequest{}
+
+	// The CreateSaml2IdentityProviderDetails implement such interface.


i would be clear that it implements the CreateIdentityProviderDetails interface here

also, did we update the descriptions for interfaces like CreateIdentityProviderDetails to mention the possible structs (subclasses) they can take? So user doesn't have to go searching through whole API reference for something that matches the interface?

not yet I have a task for that. Some services already document that others do not

jodoglevy · 2018-02-22T07:17:40Z

oci.go

+
+Pagination
+
+When calling a list operation, the operation will retrieve a page of results. To retrieve more data, call the list operation again


" call the list operation again passing" -> " call the list operation again, passing"

jodoglevy · 2018-02-22T07:19:17Z

oci.go

+
+When calling a list operation, the operation will retrieve a page of results. To retrieve more data, call the list operation again
+passing in the value of the most recent response's OpcNextPage as the value of Page in the next list operation call.
+When there is no more data the OpcNextPage field will be nil. For example: https://github.com/oracle/oci-go-sdk/blob/master/example/example_core_test.go#L86


"An example of paginating using this logic can be found here: For example: https://github.com/oracle/oci-go-sdk/blob/master/example/example_core_test.go#L86"

jodoglevy · 2018-02-22T07:20:07Z

oci.go

+The SDK has a built-in logging mechanism used internally. The internal logging logic is used to record the raw http
+requests, responses and potential errors when (un)marshalling request and responses.
+
+To expose debugging logs set the environment variable "OCI_GO_SDK_DEBUG" to "1", or some other non emtpy string.


"To expose debugging logs " -> "To expose debugging logs,"

typo: emtpy

jodoglevy · 2018-02-22T07:21:38Z

oci.go

+Forward and Backwards Compatibility
+
+Some response fields are enum-typed. In the future, individual services may return values not covered by existing enums
+for that field. To address this possibility, every enum-type response field is a model as a type that supports any string.


" is a model as a" -> " is modeled as a"

jodoglevy · 2018-02-22T07:22:36Z

oci.go

+To expose debugging logs set the environment variable "OCI_GO_SDK_DEBUG" to "1", or some other non emtpy string.
+
+
+Forward and Backwards Compatibility


This section is just on Forwards Compat. Title should remove backwards compat part

jodoglevy · 2018-02-22T07:23:10Z

oci.go

+
+Some response fields are enum-typed. In the future, individual services may return values not covered by existing enums
+for that field. To address this possibility, every enum-type response field is a model as a type that supports any string.
+Thus if a service returns a value that is not recognized by your version of the SDK, then the response field will be set to this value.


what about new subclasses for polymorphic models? should mention that as well

jodoglevy · 2018-02-22T07:24:57Z

oci.go

-Each package represents a service. These packages include methods to interact with the service, structs that model
-input and output parameters and a client struct that acts as receiver for the above methods. All code in these packages
-is machine generated.
+Licensing information available at: https://github.com/oracle/oci-go-sdk/blob/master/LICENSE.txt


'License information is available at ...'

also, https://github.com/oracle/oci-go-sdk/blob/master/LICENSE.txt doesn't have the right '2016, 2018' copyright text in it

jodoglevy · 2018-02-22T07:25:48Z

oci.go


- cmd: internal tools used by the `oci-go-sdk`
 */
 package oci


if we add retry functionality for GA, should add a section on it here as well

@shalka fyi

jodoglevy · 2018-02-22T07:26:28Z

oci.go

-there are some functions in this package that are meant for user consumption, most of them are meant to be used by the service packages.

- cmd: internal tools used by the `oci-go-sdk`
 */


what about Notifications and Questions or Feedback sections?

eginez · 2018-02-27T23:25:30Z

@jodoglevy We are going to merge this changes as they are, to update master with the lastest godocs, if we need modifications we can tackle them later.

SCOPE: preview, master Squashed commit of the following: commit 7b91e5360be814c245f1ac27c4211abf0897fdc7 Author: Esteban G <esteban.ginez@oracle.com> Date: Tue Jun 12 09:25:58 2018 -0700 DEX-3649: Hiding details on R1 url

Esteban G added 30 commits January 17, 2018 14:35

doc fixes to readme file

82be45b

fixing some typos adding text to warning

e3528dd

Adding content to README

cf58c14

Other fixes to README

8b2b833

Merge branch 'master' into eginez/docfixes

37312d8

Fixing string urls in documentation

f1b06ac

adding godoc documentation

3e33aed

adding fixes for godoc documents

2ee2c00

Adding godoc comments to auth package

a57d0b7

Applying review comments on README.md file

a1167d0

Adding go get command for installing

a6c104d

fix to warning mesage

31edec8

Merge branch 'master' into eginez/docfixes

c264a5f

addressing code review comments

2862b8a

addressing code review comments

d0d6e19

addressing code review comments

7eb4d53

modifying copyright header

750b2de

Merge branch 'master' into eginez/docfixes

9f86482

modifying copyright header

b83b799

Merge branch 'master' into eginez/docfixes

819791a

adding merge commit fix

19206f0

Adding fixes to README file

6638a7a

Adding link name back

9c2aec3

Adding . in some sentences

12cd38f

Merge branch 'master' into eginez/docfixes

b963c17

adding godoc changes

fc4b3b2

code review fixes

de656bc

Merge branch 'master' into eginez/docfixes

8674cf0

code review fixes

9284687

adding link text back

31ed75e

jodoglevy reviewed Feb 22, 2018

View reviewed changes

oci.go

//Signs the request

signer.Sign(&request)

Copy link

Contributor

jodoglevy Feb 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think the example should show making the request, once its signed, too?

jodoglevy reviewed Feb 22, 2018

View reviewed changes

Esteban G added 4 commits February 22, 2018 10:04

Merge branch 'master' into eginez/godocs

0799c8d

addresing comments

70a6110

fixing typo

41e650c

fixng client sample var name

5a7973b

eginez merged commit 0332408 into master Feb 27, 2018

eginez deleted the eginez/godocs branch February 28, 2018 00:31


		DisplayName *string `mandatory:"false" json:"displayName"`

		DisplayNumber *int `mandatory:"false" json:"dnsNumber"`


		Signing custom requests

		The oci-go-sdk exposes a stand-alone signer that can be used to sign custom requests. For example:


		Polymorphic json requests and responses

		Some operations accept or return polymorphic json objects. The SDK models such objects as an interface. Further the SDK provides


		Pagination

		When calling a list operation, the operation will retrieve a page of results. To retrieve more data, call the list operation again

		To expose debugging logs set the environment variable "OCI_GO_SDK_DEBUG" to "1", or some other non emtpy string.


		Forward and Backwards Compatibility

Godoc front page #78

Godoc front page #78

Uh oh!

Conversation

eginez commented Feb 14, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jodoglevy Feb 22, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eginez commented Feb 27, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jodoglevy Feb 22, 2018 •

edited

Loading