Generate comments for deprecated routes.

As recommended at https://blog.golang.org/godoc-documenting-go-code

Author: Diwaker Gupta

dropbox/files/client.go

@@ -47,6 +47,7 @@ type Client interface {
 	AlphaUpload(arg *CommitInfoWithProperties, content io.Reader) (res *FileMetadata, err error)
 	// Copy : Copy a file or folder to a different location in the user's
 	// Dropbox. If the source path is a folder all its contents will be copied.
+	// Deprecated: Use `CopyV2` instead
 	Copy(arg *RelocationArg) (res IsMetadata, err error)
 	// CopyBatch : Copy multiple files or folders to different locations at once
 	// in the user's Dropbox. If `RelocationBatchArg.allow_shared_folder` is
@@ -71,6 +72,7 @@ type Client interface {
 	// Dropbox. If the source path is a folder all its contents will be copied.
 	CopyV2(arg *RelocationArg) (res *RelocationResult, err error)
 	// CreateFolder : Create a folder at a given path.
+	// Deprecated: Use `CreateFolderV2` instead
 	CreateFolder(arg *CreateFolderArg) (res *FolderMetadata, err error)
 	// CreateFolderV2 : Create a folder at a given path.
 	CreateFolderV2(arg *CreateFolderArg) (res *CreateFolderResult, err error)
@@ -79,6 +81,7 @@ type Client interface {
 	// indicates that the file or folder was deleted. The returned metadata will
 	// be the corresponding `FileMetadata` or `FolderMetadata` for the item at
 	// time of deletion, and not a `DeletedMetadata` object.
+	// Deprecated: Use `DeleteV2` instead
 	Delete(arg *DeleteArg) (res IsMetadata, err error)
 	// DeleteBatch : Delete multiple files/folders at once. This route is
 	// asynchronous, which returns a job ID immediately and runs the delete
@@ -159,6 +162,7 @@ type Client interface {
 	ListRevisions(arg *ListRevisionsArg) (res *ListRevisionsResult, err error)
 	// Move : Move a file or folder to a different location in the user's
 	// Dropbox. If the source path is a folder all its contents will be moved.
+	// Deprecated: Use `MoveV2` instead
 	Move(arg *RelocationArg) (res IsMetadata, err error)
 	// MoveBatch : Move multiple files or folders to different locations at once
 	// in the user's Dropbox. This route is 'all or nothing', which means if one
@@ -215,6 +219,7 @@ type Client interface {
 	Upload(arg *CommitInfo, content io.Reader) (res *FileMetadata, err error)
 	// UploadSessionAppend : Append more data to an upload session. A single
 	// request should not upload more than 150 MB.
+	// Deprecated: Use `UploadSessionAppendV2` instead
 	UploadSessionAppend(arg *UploadSessionCursor, content io.Reader) (err error)
 	// UploadSessionAppendV2 : Append more data to an upload session. When the
 	// parameter close is set, this call will close the session. A single

dropbox/sharing/client.go

@@ -44,6 +44,7 @@ type Client interface {
 	AddFolderMember(arg *AddFolderMemberArg) (err error)
 	// ChangeFileMemberAccess : Identical to update_file_member but with less
 	// information returned.
+	// Deprecated: Use `UpdateFileMember` instead
 	ChangeFileMemberAccess(arg *ChangeFileMemberAccessArgs) (res *FileMemberActionResult, err error)
 	// CheckJobStatus : Returns the status of an asynchronous job. Apps must
 	// have full Dropbox access to use this endpoint.
@@ -64,6 +65,7 @@ type Client interface {
 	// the corresponding file or folder. In the future, this will no longer be
 	// the case, so your app shouldn't rely on this behavior. Instead, if your
 	// app needs to revoke a shared link, use `revokeSharedLink`.
+	// Deprecated: Use `CreateSharedLinkWithSettings` instead
 	CreateSharedLink(arg *CreateSharedLinkArg) (res *PathLinkMetadata, err error)
 	// CreateSharedLinkWithSettings : Create a shared link with custom settings.
 	// If no settings are given then the default visibility is
@@ -89,6 +91,7 @@ type Client interface {
 	// all shared links that allow access to the given path.  Collection links
 	// are never returned in this case. Note that the url field in the response
 	// is never the shortened URL.
+	// Deprecated: Use `ListSharedLinks` instead
 	GetSharedLinks(arg *GetSharedLinksArg) (res *GetSharedLinksResult, err error)
 	// ListFileMembers : Use to obtain the members who have been invited to a
 	// file, both inherited and uninherited members.
@@ -170,6 +173,7 @@ type Client interface {
 	RelinquishFolderMembership(arg *RelinquishFolderMembershipArg) (res *async.LaunchEmptyResult, err error)
 	// RemoveFileMember : Identical to remove_file_member_2 but with less
 	// information returned.
+	// Deprecated: Use `RemoveFileMember2` instead
 	RemoveFileMember(arg *RemoveFileMemberArg) (res *FileMemberActionIndividualResult, err error)
 	// RemoveFileMember2 : Removes a specified member from the file.
 	RemoveFileMember2(arg *RemoveFileMemberArg) (res *FileMemberRemoveActionResult, err error)

dropbox/team/client.go

@@ -39,6 +39,7 @@ type Client interface {
 	// DevicesListMembersDevices : List all device sessions of a team.
 	DevicesListMembersDevices(arg *ListMembersDevicesArg) (res *ListMembersDevicesResult, err error)
 	// DevicesListTeamDevices : List all device sessions of a team.
+	// Deprecated: Use `DevicesListMembersDevices` instead
 	DevicesListTeamDevices(arg *ListTeamDevicesArg) (res *ListTeamDevicesResult, err error)
 	// DevicesRevokeDeviceSession : Revoke a device session of a team's member
 	DevicesRevokeDeviceSession(arg *RevokeDeviceSessionArg) (err error)
@@ -109,6 +110,7 @@ type Client interface {
 	// LinkedAppsListTeamLinkedApps : List all applications linked to the team
 	// members' accounts. Note, this endpoint doesn't list any team-linked
 	// applications.
+	// Deprecated: Use `LinkedAppsListMembersLinkedApps` instead
 	LinkedAppsListTeamLinkedApps(arg *ListTeamAppsArg) (res *ListTeamAppsResult, err error)
 	// LinkedAppsRevokeLinkedApp : Revoke a linked application of the team
 	// member

generator/go_helpers.py

@@ -1,4 +1,4 @@
-from stone.api import ApiNamespace
+from stone.api import (ApiNamespace, ApiRoute)
 from stone.data_type import (
     Boolean,
     Float32,
@@ -118,6 +118,13 @@ def generate_doc(code_generator, t):
         d = 'Package %s : %s' % (t.name, doc)
     code_generator.emit_wrapped_text(d, prefix='// ')
 
+    # Generate comment for deprecated routes
+    if isinstance(t, ApiRoute):
+        if t.deprecated is not None:
+            d = 'Deprecated: '
+            if t.deprecated.by is not None:
+                d += 'Use `%s` instead' % fmt_var(t.deprecated.by.name)
+            code_generator.emit_wrapped_text(d, prefix='// ')
 
 def _needs_base_type(data_type):
     if is_struct_type(data_type) and data_type.has_enumerated_subtypes():