推送 API 文档的一些问题点

[jwfing]

1. /1.1/push 推送通知这里请求体的记录感觉特别混乱，完全看不出有什么格式可言。例如「iOS 设备推送消息内容」一节，不知道谁能总结一个 request 的 schema 出来？android 那里也是，搞不清楚华为/小米究竟应该怎么发请求——考虑到华为/小米有很多自己的参数，该如何传递是没有说明的。
2. 这篇文档里面很多概念的说明，都没有自己的解释，而是抛一个第三方的链接，需要开发者自己去第三方那里看一遍，搞明白之后再回来看我们的文档，这样的方式是会导致巨大的学习成本的。更好的做法应该是我们把含义说清楚，告知开发者该怎么使用它，然后开发者有兴趣钻研更多的话，他们可以去参考 xx 文档。
3. 例子太少，例如「iOS 设备推送消息内容」一节，误把字段定义当成了 sample code，然后真正的例子是缺失的。
4. 其他一些小问题。例如：

• 「“collapse-id”: 字符串类型，对应 APNs request header 的 apns-collapse-id 参数，用于多条推送合并展示，具体请点击下面 Apple 官方关于 Request Header 的文档链接进行查阅,」这里最后的标点符号是（半角）逗号，是什么意思呢？还有「下面 Apple 官方关于 Request Header 的文档」链接在哪里呢？
• 前后矛盾。例如查询推送记录的 path，推送消息一节写的是 /1.1/notifications/:notification_id，推送记录查询一节写的是 /1.1/tables/Notifications/:objectId；