If API maintainers can't maintain their own documentation when it's directly adjacent to the API definition, what makes anyone think they would do it in a separate, decoupled document?
This is not a technology issue. It's simple: People need to write the docs. The process (reviewers, Jenkins) needs to reject patches without them. Where they go is irrelevant if nobody writes it in the first place. Chris. > -----Original Message----- > From: vpp-dev-boun...@lists.fd.io [mailto:vpp-dev-boun...@lists.fd.io] On > Behalf Of Ole Troan > Sent: Thursday, January 18, 2018 3:33 > To: Jon Loeliger <j...@netgate.com> > Cc: vpp-dev <vpp-dev@lists.fd.io> > Subject: Re: [vpp-dev] Heads up: VPPAPIGEN rewrite > > Hi Jon, > > > Can we add to the "Future Plans" list? > > I would like to see it draw a correlation between a message's actual > > list of fields and the attempt at a documentation for those fields. > > Specifically, there always seems to be some discrepancy and it is hard > > to tell which to believe without then going and reading the code. > > If the fields and doc lines for the fields at least agreed on which > > fields were present, that would be a start. > > I find embedded documentation (and excessive comments) problematic for > that exact reason. > We're never going to make them consistent. > > Stepping back a little; I think we agree that the API, being the main > interface > outside of VPP, should have good documentation. > I don't think doxygen tags in the .api files can ever be that. > If you agree with that, do you have better suggestions? > Given that we have multiple language bindings, interactive documentation > like what Swagger has might be one option? > > Best regards, > Ole > _______________________________________________ vpp-dev mailing list vpp-dev@lists.fd.io https://lists.fd.io/mailman/listinfo/vpp-dev
