Add package level documentation for db, historydb, l2db and api/...

db/historydb/historydb.go

@@ -1,3 +1,24 @@
+/*
+Package historydb is responsible for storing and retrieving the historic data of the Hermez network.
+It's mostly but not exclusively used by the API and the synchronizer.
+
+Apart from the logic defined in this package, it's important to notice that there are some triggers defined in the
+migration files that have to be taken into consideration to understanding the results of some queries. This is especially true
+for reorgs: all the data is directly or indirectly related to a block, this makes handling reorgs as easy as deleting the
+reorged blocks from the block table, and all related items will be dropped in cascade. This is not the only case, in general
+functions defined in this package that get affected somehow by the SQL level defined logic has a special mention on the function description.
+
+Some of the database tooling used in this package such as meddler and migration tools is explained in the db package.
+
+This package is spitted in different files following these ideas:
+- historydb.go: constructor and functions used by packages other than the api.
+- apiqueries.go: functions used by the API, the queries implemented in this functions use a semaphore
+to restrict the maximum concurrent connections to the database.
+- views.go: structs used to retrieve/store data from/to the database. When possible, the common structs are used, however
+most of the time there is no 1:1 relation between the struct fields and the tables of the schema, especially when joining tables.
+In some cases, some of the structs defined in this file also include custom Marshallers to easily match the expected api formats.
+- nodeinfo.go: used to handle the interfaces and structs that allow communication across running in different machines/process but sharing the same database.
+*/
 package historydb
 
 import (

db/l2db/l2db.go

@@ -1,3 +1,20 @@
+/*
+Package l2db is responsible for storing and retrieving the data received by the coordinator through the api.
+Note that this data will be different for each coordinator in the network, as this represents the L2 information.
+
+The data managed by this package is fundamentally PoolL2Tx and AccountCreationAuth. All this data come from
+the API sent by clients and is used by the txselector to decide which transactions are selected to forge a batch.
+
+Some of the database tooling used in this package such as meddler and migration tools is explained in the db package.
+
+This package is spitted in different files following these ideas:
+- l2db.go: constructor and functions used by packages other than the api.
+- apiqueries.go: functions used by the API, the queries implemented in this functions use a semaphore
+to restrict the maximum concurrent connections to the database.
+- views.go: structs used to retrieve/store data from/to the database. When possible, the common structs are used, however
+most of the time there is no 1:1 relation between the struct fields and the tables of the schema, especially when joining tables.
+In some cases, some of the structs defined in this file also include custom Marshallers to easily match the expected api formats.
+*/
 package l2db
 
 import (

db/utils.go

@@ -1,3 +1,10 @@
+/*
+Package db have some common utilities shared by db/l2db and db/historydb, the most relevant ones are:
+- SQL connection utilities
+- Managing the SQL schema: this is done using migration files placed under db/migrations. The files are executed by
+order of the file name.
+- Custom meddlers: used to easily transform struct <==> table
+*/
 package db
 
 import (