Bug 1467

Summary: Sync class header comments with reference manual
Product: [Documentation] Reference Reporter: Scott Garman <scott.a.garman>
Component: handbookAssignee: Michael Opdenacker <michael.opdenacker>
Status: RESOLVED WONTFIX QA Contact:
Severity: enhancement    
Priority: Low CC: jessica.zhang, mark.hatle, poky.bs.watcher, poky.doc.watcher, poky.watcher, randy.macleod, richard.purdie, sgw
Version: 1.0   
Target Milestone: Future   
Hardware: x86   
OS: Multiple   
Whiteboard:
OS type for building Yocto: --- Type of Regression: ---
Verified: Documentation change: Yes (doc changes required)

Description Scott Garman 2011-09-09 03:16:54 UTC 
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.
Comment 1 Scott Rifenbark 2011-09-09 08:28:59 UTC 
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.
Comment 2 Scott Rifenbark 2012-04-24 22:59:28 UTC 
Changed the component to Handbook.  Needs to be "Reference Manual" when we have that category.
Comment 3 Scott Rifenbark 2013-03-20 20:18:25 UTC 
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.
Comment 4 Paul Eggleton 2013-12-18 11:32:05 UTC 
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.
Comment 5 Mark Hatle 2014-05-03 17:29:42 UTC 
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.
Comment 6 Michael Opdenacker 2023-09-13 12:17:35 UTC 
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.