[ObjC] generated method name's WithCompletionBlock postfix doesn't follow convention?

[hideya]

API methods for Obj-C always seems to have WithCompletionBlock postfix, which doesn't follow the coding convention. For example, I think the following generated method:

-(NSNumber*) userConfirmWithCompletionBlock :(NSString*) uid 
     token:(NSString*) token 
     redirect:(NSString*) redirect 
    completionHandler: (void (^)(NSError* error))completionBlock;

should have been like the following:

-(NSNumber*) userConfirmWithUid :(NSString*) uid 
     token:(NSString*) token 
     redirect:(NSString*) redirect 
    completionHandler: (void (^)(NSError* error))completionBlock;

FYI, the yaml for this method is:

  /Users/confirm:
    get:
      tags:
        - User
      summary: Confirm a user registration with email verification token.
      description: !<tag:yaml.org,2002:js/undefined> ''
      operationId: User.confirm
      parameters:
        - name: uid
          in: query
          description: !<tag:yaml.org,2002:js/undefined> ''
          required: true
          type: string
        - name: token
          in: query
          description: !<tag:yaml.org,2002:js/undefined> ''
          required: true
          type: string
        - name: redirect
          in: query
          description: !<tag:yaml.org,2002:js/undefined> ''
          required: false
          type: string
      responses:
        '204':
          description: Request was successful
          schema: !<tag:yaml.org,2002:js/undefined> ''
      deprecated: false

This is as of b54947d (the current latest) (@bajtos wanted to keep informed about this too)

[wing328]

@hideya do you mean the postfix (WithCompletionBlock) is causing compiling error?

[hideya]

@wing328 no, this is an improvement request, as e.g. userConfirmWithCompletionBlock doesn't follow Obj-C method naming convention. Sorry for being unclear.

[wing328]

I see. For the naming convention, do you have the URL to the style guide for our reference?

[hideya]

Sure. Apple's Guide to Naming Methods says that:

Make the word before the argument describe the argument.

• (id)viewWithTag:(NSInteger)aTag; -- Right.
• (id)taggedView:(int)aTag; -- Wrong.

[wing328]

Thanks for the URL. Using the example User.confirm you provide, you suggest naming it as userConfirmWithUid where uid is the first argument (in Pascal case).

The easiest fix I can think of is to rename operationId to userConfirmWithUid but of course the side effect is that other API clients would use the same method name (assuming API client in other langauges is used)

To fix it just for ObjC, one needs to customize the ObjC generator to provide another mustache tag (e.g. firstParameter), which stores the name of the 1st method argument in Pascal case. This can be done in Map<String, Object> postProcessOperations(Map<String, Object> objs)

[hideya]

Thanks for the explanation. Yeah, I'd like to have it fixed just for ObjC.
Would you willing to take the change if I worked on a PR for it? (although it is a compatibility breaking change in terms of ObjC client SDKs people already have generated...)

[wing328]

I don't mind. To me it's ok to make this breaking change (non-backward compatible) as your suggestion is better in terms of conforming to Apple's guidelines in naming method.

Later we can include this in the release note or migration guide to make sure developers are informed of this breaking change when they upgrade to the next stable release.

[hideya]

Thanks! I'll work on it then!