Project

General

Profile

action #162698

Updated by ybonatakis 6 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:**  

 ## 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?

Back