[yocto] oe-selftest documentation

[Rifenbark, Scott M]

>-----Original Message-----
>From: yocto-bounces at yoctoproject.org [mailto:yocto-
>bounces at yoctoproject.org] On Behalf Of Stoicescu, CorneliuX
>Sent: Wednesday, March 19, 2014 5:50 AM
>To: yocto at yoctoproject.org
>Cc: Purdie, Richard; Eggleton, Paul
>Subject: [yocto] oe-selftest documentation
>
>Hello,
>
>We have oe-selftest already integrated in poky but we lack in documentation:
>https://bugzilla.yoctoproject.org/show_bug.cgi?id=4740
>
>Here is what I am thinking about what could be done and I would like opinions
>on what should be done:
>1) We can do a wiki entry to describe in detail how to use oe-selftest and give
>examples. The problem here is that as oe-selftest changes this entry might
>become outdated and even if we update it then older Yocto releases users
>will not be able to use it anymore.

You can solve the "out-dated" problem by having sections in the wiki specific to various releases.

>2) We can have a manual entry derived from the wiki entry. Scott can use the
>wiki entry as a reference, if we decide to have one, to create the manual
>entry. The advantage of this is that we will have valid and up to date
>information for each Yocto release.

If you have a manual entry for the feature then it will be correct for that release of the YP.  The wiki then becomes a spot for detailed information that would need to be common across all releases of the manual (e.g. concepts, basic information that does not change from release to release, etc.).  Note that that information could just as well be in the manual thus eliminating the need for the wiki entry.

>3) We can introduce comments in the script to explain what and why it does
>what it does(at the moment we have some though)

This is a good idea regardless of what you do.  You should self-document the script with comments.  It would help me out as well.

>4) We can introduce comments in test modules or a DESCRIPTION field to
>document the test steps, especially for more complex tests(we have no such
>comments at the moment).

This is a good idea also regardless of what you do.  The more in-line explanation the better.

>
>I would opt for 2) and 3) as I believe they give the most value with the least
>amount of time needed for creation and maintenance.
>
>If anyone has any more ideas please add your thoughts.
>
>Regards,
>Corneliu
>--
>_______________________________________________
>yocto mailing list
>yocto at yoctoproject.org
>https://lists.yoctoproject.org/listinfo/yocto