When it comes to reference documentation for the federation protocol, client to pod api, and pod to pod API, and any other service included in the reference pod implementation, should have reference documentation that is autogenerated from a single source of truth. This could be the code itself (through markup of some kind in the comments) or preferably from another format like XML so that developers can more easily generate proxies in whatever programming language or tooling they want. If from XML, then the associated code models in the reference implementation need to be generated from the same XML source, just as any other alternative pod implementation would be. This way the reference documentation will always be up to date, at least in terms of the property names, as applicable, and perhaps simple or extensible type annotations (date, decimal, string, bool, custom type, etc). on top of this basic information, some supporting documentation could be added, similar to xml docs in c# or similar tools.
SleepyDaddySoftware · Wed 12 Sep 2012 11:25PM
When it comes to reference documentation for the federation protocol, client to pod api, and pod to pod API, and any other service included in the reference pod implementation, should have reference documentation that is autogenerated from a single source of truth. This could be the code itself (through markup of some kind in the comments) or preferably from another format like XML so that developers can more easily generate proxies in whatever programming language or tooling they want. If from XML, then the associated code models in the reference implementation need to be generated from the same XML source, just as any other alternative pod implementation would be. This way the reference documentation will always be up to date, at least in terms of the property names, as applicable, and perhaps simple or extensible type annotations (date, decimal, string, bool, custom type, etc). on top of this basic information, some supporting documentation could be added, similar to xml docs in c# or similar tools.