This is a feature enhancement bug for tracking an idea related to our method of source code documentation. I've been asked during presentations when introducing recipes, where one can go to find a list of the variables a BitBake class uses that a recipe writer may want to override. Currently, we have some information about this in the Poky Reference Manual, but it's generally scattered about and is far from complete. One idea proposed is to have a standardized format comment header at the top of each .bbclass file which outlines which variables are used for what, to give class users a quick overview of the information they need without having to wade through the entire class's source code. No doubt there are other ways of doing this, too. This enhancement bug is being filed to note this issue and track its resolution.
This is a good idea. If we had descriptions of variables in the headers then I could easily create a growing variable index that would be much better than what we currently have in the Yocto Project Reference Manual.
Changed the component to Handbook. Needs to be "Reference Manual" when we have that category.
It would be good if we had these variables commented as Scott Garman suggests in the headers. I can't do anything in the reference manual to collect this information. I will want to document individual variables as they become available through the headers. Any progress on changing our source code documentation policies for these variables? Scott R.
We've now added documentation for every class to the reference manual. The only remaining thing would be to try to merge that back into header comments in the classes, especially for those that currently don't have any such header.
From OEDAM discussion: * can we do doxygen or some other programmatic way to get manual info from classes, and make the bbclass the canonical source Concern is that this will add overhead to the documentation development and make it difficult, even programmatically to keep up to date. * Instead we should add links in each bbclass to the documentation, perhaps with a note that indicates to make sure to send updates to the documentation if variables are changes/updated.
I don't think it's a good idea to add more constraints on implementing classes. In addition, you may not want to document all variables controlling a class. Sometimes, some variables are meant to be used in very specific cases and you don't want to distract documentation readers from the big picture. Closing this bug. Don't hesitate to comment and re-open it if you disagree.