action #162698
Updated by ybonatakis 5 months ago
## Observation The idea is to make the documentation in OpenQA more explanatory and helpful. ##### Example of not very useful description There are many example but I will point you to [create_artefact](https://github.com/os-autoinst/openQA/blob/master/lib/OpenQA/WebAPI/Controller/API/V1/Job.pm#L648) function. ``` perl =item create_artefact() Used by the worker to upload files to the test. =back =cut ``` Without read the code is hard to understand what it does or answer questions like: - Can you tell what is the input and what the expected output? ##### Example of missing documentation [OpenQA::WebAPI::Controller::API::V1::JobSettings::jobs](https://github.com/os-autoinst/openQA/blob/master/lib/OpenQA/WebAPI/Controller/API/V1/JobSettings.pm#L7) ##### Example of a better description I consider [get_parents](https://github.com/os-autoinst/openQA/blob/master/lib/OpenQA/WebAPI/Controller/API/V1/Mm.pm#L87) a good example Enhance/Improve OpenQA perldoc This was an idea raised by @ybonatakis. ## Acceptance criteria * **AC1:** functions under lib/OpenQA provides a short description * **AC2:** At least expected inputs/outputs are documented. ## Suggestions * I don't want to write pod. * extract and refactor if function is too big and while writing a documentation you find mismatch between the name what the function * Do we publish html of the pods? * Opportunity to play with AI stuff?