On Thu, Jan 18, 2018 at 2:32 AM, Ole Troan <otr...@employees.org> wrote:
> Hi Jon, > > I find embedded documentation (and excessive comments) problematic for > that exact reason. > Absolutely agree 100%. > We're never going to make them consistent. > Sadly, correct again. > Stepping back a little; I think we agree that the API, being the main > interface outside of VPP, should have good documentation. > Yes. > I don't think doxygen tags in the .api files can ever be that. > Agreed. > If you agree with that, do you have better suggestions? > Carry a large stick and use it frequently? Perhaps on every commit? :-) > Given that we have multiple language bindings, interactive documentation > like what Swagger has might be one option? > So, I might caution that this runs the risk of introducing a whole bunch of complexity and dependency where we might not need more. We need better writing and a willingness to write more complete sentences with an eye toward understanding that the details are maybe not yet obvious to the API user. That is, we need better content, not a more complex system to manage the content. Best regards, > Ole > HTH, jdl
_______________________________________________ vpp-dev mailing list vpp-dev@lists.fd.io https://lists.fd.io/mailman/listinfo/vpp-dev
