Add POD documentation for lib/known_bugs #7495
Conversation
| This will be used in main.pm to initialize the backend with that list | ||
| To add a known bug simply copy and adapt the following line: | ||
| C<push @$serial_failures, {type => soft/hard, message => 'Errormsg', pattern => quotemeta 'ErrorPattern' }> | ||
| =cut |
There was a problem hiding this comment.
For retro compatibility, we need to add a space before cut.
lib/known_bugs.pm
Outdated
| =head1 SYNOPSIS | ||
|
|
||
| Allow detection of known errors on the serial console | ||
| =cut |
There was a problem hiding this comment.
For retro compatibility, we need to add a space before cut.
| =cut | |
| =cut |
| @@ -28,12 +28,21 @@ our @EXPORT = qw( | |||
| upload_journal | |||
| ); | |||
|
|
|||
| =head1 SYNOPSIS | |||
There was a problem hiding this comment.
This line is more useful if it contains the name of the module, when the doc is generated apart from the code.
There was a problem hiding this comment.
In utils.pm we have this style somehow established, if your intention is to clarify what module we are on, this could be done via the page title?
Where else would you place the synopsis? On an own head2?
| C<push @$journal_failures, {type => soft/hard, message => 'Errormsg', pattern => quotemeta 'ErrorPattern' }> | ||
| type=soft will force the testmodule result to softfail | ||
| type=hard will just emit a soft fail message but the module will do a normal fail | ||
| =cut |
There was a problem hiding this comment.
| =cut | |
| =cut |
|
|
||
| Checks the journal for known patterns defined in $journal_failures | ||
| Do not touch unless you know what you're doing | ||
| =cut |
There was a problem hiding this comment.
| =cut | |
| =cut |
|
I would add something in general section about our struggle - that on one side we don't want to fail test case when we found something so we would like to go with softfailure but on other side we can't be smart enough to identify some certain bug so we end up breaking rule about softfailure and bug assignment |
DrMullings
force-pushed
the
documentation
branch
3 times, most recently
from
74dfa7c
to
4380e63
Compare
|
Updated according our agreement |
|
|
||
| =cut | ||
|
|
||
| =head2 create_list_of_serial_failures |
There was a problem hiding this comment.
I am missing the synopsis of the functions. @foursixnine ?
| =head2 create_list_of_serial_failures | |
| =head2 create_list_of_serial_failures | |
| $ref_to_list = create_list_of_serial_failures() |
There was a problem hiding this comment.
There is no synopsis, as this function is not intended to be called by the end-user, but only to be extended with new serial failures
There was a problem hiding this comment.
I thought this documentation is for the code in general, not only for end-users.
There was a problem hiding this comment.
I agree with @SergioAtSUSE's comment. However I'd use it differently, mostly because we should ilustrate the test developer how to interact with this. While it is documented at the os-autoinst/distribution.pm level, extending a bit here, doesn't hurt.
| =head2 create_list_of_serial_failures | |
| =head2 create_list_of_serial_failures | |
| my $list = create_list_of_serial_failures(); | |
| $testapi::distri->set_expected_serial_failures($list); | |
There was a problem hiding this comment.
but, don't forget the blank line after =head2
lib/known_bugs.pm
Outdated
|
|
||
| =head1 SYNOPSIS | ||
|
|
||
| C<use lib/known_bugs> |
There was a problem hiding this comment.
| C<use lib/known_bugs> | |
| C<use lib::known_bugs> |
|
|
||
| =cut | ||
|
|
||
| =head2 create_list_of_serial_failures |
There was a problem hiding this comment.
I agree with @SergioAtSUSE's comment. However I'd use it differently, mostly because we should ilustrate the test developer how to interact with this. While it is documented at the os-autoinst/distribution.pm level, extending a bit here, doesn't hurt.
| =head2 create_list_of_serial_failures | |
| =head2 create_list_of_serial_failures | |
| my $list = create_list_of_serial_failures(); | |
| $testapi::distri->set_expected_serial_failures($list); | |
lib/known_bugs.pm
Outdated
|
|
||
| =head2 create_list_of_serial_failures | ||
|
|
||
| Creates the list of known bug patterns on the serial logs |
There was a problem hiding this comment.
| Creates the list of known bug patterns on the serial logs | |
| Returns the list of known bug patterns on the serial logs |
Adding basic documentation for the known_bugs module
|
And another update |
|
LGTM |
Adding basic documentation for the known_bugs module