Add complete documentation to all the functions and files

[amtoine]

Describe your request

Before moving on to the 3 opened priority:high issues, i wanted to make the code base slightly easier to work with, at least according to me :yum:

Right now, some of the functions and files of bsp-layout are missing documentation.

I would like to add:

• comments on some parts that might be unclear to the new user or the new devs
• docstrings on all the functions to have a clear description available directly in the code base
• signature annotations for all the functions, i.e. input argument and output return values if they exist.

Briefly explain its use-case

The docstrings and the signatures should be discussed here.

Docstrings:

foo () {
  # Does something.
  # 
  # Args:
  #   arg1 (type1): this is the first argument
  #   arg2 (type2): this is the second argument
  # 
  # Returns:
  #   return_value (type_return): this is the return value
  # 
  bar
  baz
  ...
}

Signatures: do we use someting like

# (Data ->) :: Key -> Value -> Data
append_option() { sed "/^$1:/d"; echo "$1:$2"; }

or something more spread across the docstring like in the docstring example above?

[phenax]

I think a more compact signature would be better along with a couple of lines explaing the code if necassary. docstring-style imo is way too verbose and fogs up the code a bit. Also, in some cases, it'll be better to rename the function to be self-explanatory instead of adding 4 lines in the comments explaining what it does.

[amtoine]

I think a more compact signature would be better along with a couple of lines explaing the code if necassary. docstring-style imo is way too verbose and fogs up the code a bit.

i can propose something in a PR if that's ok with you :blush:

Also, in some cases, it'll be better to rename the function to be self-explanatory instead of adding 4 lines in the comments explaining what it does.

yep agree on that :ok_hand: