Naming on IChangeSetItemAuthorizer is inconsistent

[robertmclaws]

If you look at other classes in the .NET Framework that implement some kind of same-type parent-child relationship, the naming convention is typically Inner{TypeName}. For example, Exception has a property called InnerException. "Inner" is always used as a prefix, and never by itself.

However, the IChangeSetItemAuthorizer in RESTier does not follow this convention. According to http://restier.readthedocs.io/en/latest/server/method-authorization/#centralized-authorization, the property is just named Inner.

Normally I would recommend adding the proper suffix in this situation. But because the two interfaces involved (IChangeSetItemAuthorizer vs IChangeSetItemProcessor) are totally different, I recommend changing the property name from Inner to either ChangeSetProcessor or ChangeSetItemProcessor. That would be much clearer to the developer that they are actually two separate things, and that they are used differently.

Assemblies affected

RESTier 0.5.0-beta

[chinadragon0515]

@advancedrei from code view, it does not care the name, it only care the type and can be set, it does not care about name or accessible.

You can refer to http://odata.github.io/RESTier/#04-03-Api-Service
"Please note that if you want to call the inner builder, you need to put a settable property of IModelBuilder into your builder class. The accessibility and the name of the property doesn’t matter here. "

I find the sample is created by you, you can change to name line InnerAuthorizer or any other name, let me know if you have any more concerns.

BTW, seems http://restier.readthedocs.io/en/latest/ is built by you, our official document site is http://odata.github.io/RESTier/, we are highly welcomed and appreciated contributions to the document to help as more as possible consumers.

[robertmclaws]

A few points: 1) The ReadTheDocs website is where I am working on the updated documentation I'm going to submit. The documentation experience you have right now is a not very usable (and I just spent a week solid with it), that's why I'm using the same framework the ASP.NET team is using for their docs, instead of contributing changes to yours. Don't worry about where it lives right now, we'll deal with that later.

2. I've seen the other documentation, that's how I discovered the problem. It's not about the code understanding what to do, it's the fact that the naming is inconsistent to other humans. "Inner" only makes sense when the "Outer" type is the same. If they aren't, then it's not an "Inner" anything, it's just a property. From your example:

public class CustomizedAuthorizer : IChangeSetItem**Authorizer**{
    // The inner handler will call CanUpdate/Insert/Delete<EntitySet> method
    private IChangeSetItem**Processor** Inner { get; set; }

    public Task<bool> AuthorizeAsync(
        SubmitContext context,
        ChangeSetItem item,
        CancellationToken cancellationToken)
    {
        // Nothing is setting the "Inner" property in this sample...
    }
}

Because the example I linked to (which is ported over from the old docs) does not set the value of the property like the IModelBuilder sample you linked to, it appears that the RESTier framework sets it as it is initialized. That's why I opened the issue. If that is not the case, then the sample is missing something that wires the two together, and needs to be corrected.

[chinadragon0515]

@advancedrei that's a defect, Inner is always the same type with the class defined it. Refer to PR #423 for the fix, let me know if you have other concerns on Inner name part.

And let me know if any other items you want to track with this issue.

For the document structure, we can discuss with #418, thanks.

[chinadragon0515]

@advancedrei can we get this issue closed and work on document structure with #418 ?