Hey folks,
I'd like to talk about the current state of VPP's developer documentation. Overall, I'd say that VPP's developer documentation is severely lacking. As harsh as this sounds, I trust everyone knows that this is in no way meant as an attack or critique on a specific person. I recognize that VPP is a very complex project due to its performance goals, and there will always be a learning curve, but to me it seems like the learning curve is far, far steeper than it should and could be. I would go as far as saying that this is a significant barrier to VPP contribution. Some examples: - vlib_buffer_enqueue_to_next is completely undocumented. While one could argue that the vlib_validate_buffer_enqueue_.. functions are *somehow* documented, vlib_buffer_enqueue_to_next is still used in many places in the built-in plugins - vnet_feature_next is also completely undocumented, some info can be found on the mailing list https://lists.fd.io/g/vpp-dev/topic/questions_abount/102777199 but this cannot be the way - VLIB_NODE_FN is also undocumented - sure, some external docs tell you that you need it to register nodes, but this can also not be the way.. Sometimes you can find information on the mailing list, or some presentations, or by watching an ancient video https://www.youtube.com/watch?v=4oxYNv0gOeY, but I don't think this qualifies as proper, good documentation. There is one field report here: https://github.com/aregm/nff-go/wiki/VPP-vs-NFF-Go:-Productivity-Comparison/e4a00b2fd29a675123ecbd53a5d9e17453073050 And yes, sure, it is possible that it's a bit biased, but I can completely understand the experiences described there. >From my POV, the most important points to tackle are - Document: How exactly do I get information in and out of my node: This is a big point. It needs explanation of all the common functions like vlib_buffer_enqueue_to_next, vnet_feature_next, vlib_validate_buffer_enqueue_... - Document: How does the graph exactly work: How do feature arcs works VISUALIZED including runs_before and runs_after, static vs dynamic next nodes, etc... - Document: All the performance optimizations: Pipeline infra, prefetch walkthrough, writing code is correct despite the code duplication, etc... - Use the above docs to add more documentation to the code itself Are there documentation efforts I'm missing? What does the community think about this? Cheers, Robin
-=-=-=-=-=-=-=-=-=-=-=- Links: You receive all messages sent to this group. View/Reply Online (#26648): https://lists.fd.io/g/vpp-dev/message/26648 Mute This Topic: https://lists.fd.io/mt/116778994/21656 Group Owner: [email protected] Unsubscribe: https://lists.fd.io/g/vpp-dev/leave/14379924/21656/631435203/xyzzy [[email protected]] -=-=-=-=-=-=-=-=-=-=-=-
