Created Issue: Improve experience for users trying to write a custom parser from the default Odata path parser. [627]

Scenario: User wants to have the urls like this: "http://.../Products/10/ExtendSupportDate" without the '(' and ')' for keys.

I implemented a custom parser like below:

public class MyODataPathParser : ODataPathParser
{
public MyODataPathParser(IEdmModel model)
: base(model)
{
}

protected internal override IEnumerable<string> ParseSegments(string relativePath)
{
return relativePath.Split('/').Where(sg => sg.Length > 0);
}

protected override ODataPathSegment ParseAtEntityCollection(ODataPathSegment previous, string segment)
{
//check if the segment is key, if yes modify the segment to the format that the default parser expects
int key = -1;
if (Int32.TryParse(segment, out key))
{
segment = "(" + segment + ")";
}

return base.ParseAtEntityCollection(previous, segment);
}
}

Overall writing a custom parser for my scenario was simple, but following are some observations:

a. A user would need to understand that he has to override ParserAtEntityCollection for what I am doing above. But how would a user know that as someone needs to know about the internal logic?

b. Should we have more documentation on the individual overridable methods like ParseAtEntity, ParseAtEntityCollection etc to mention what possible things that the method looks for? for example: ParseAtEntityCollections looks for key, then cast and then bindable actions.