Add complete documentation to all the functions and files

[Antoine Stevan]

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 😋

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?

[Akshay Nair]

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.

[Antoine Stevan]

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 😊

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 👌