add: docs (mainly docstrings)

docs/make.jl

@@ -8,7 +8,10 @@ DocMeta.setdocmeta!(
     recursive = true,
 )
 
-links = InterLinks("DataFrames" => "https://dataframes.juliadata.org/dev/objects.inv")
+links = InterLinks(
+    "DataFrames" => "https://dataframes.juliadata.org/dev/objects.inv",
+    "Dates" => "https://docs.julialang.org/en/v1/objects.inv",
+)
 
 makedocs(
     modules = [PSBoardDataBase],

docs/src/about_software.md

@@ -6,14 +6,35 @@ CurrentModule = PSBoardDataBase
 このリポジトリにあるのは、JATHub masterのログファイル、及びGoogle SheetsからエクスポートしたCSVファイルからデータベースを作成するためのコードである。
 メインの関数は[`create_database_from_exported_csvs`](@ref)である。
 
-## テストについて
+## 動かし方
+[Julia](https://julialang.org)は[juliaup](https://github.com/JuliaLang/juliaup)でインストールする。
+リポジトリのルート(`Project.toml`がある)で
+```
+$ julia --project
+```
+をするとJuliaのREPLが立ち上がる。
+
+`]`をおして`Pkg`モードに入り、`instantiate`を実行すると、必要なパッケージを自動でインストールする。
+
+backspaceでjulianモードに戻り(左側が`julia>`になってる)、`using PSBoardDataBase`をすると使えるようになる。
+
+`?`を押すとhelpモードに入り、関数名などをいれるとそのドキュメント(下にあるものと同じ)が閲覧できる。
+
+`PSBoardDataBase.create_database_from_exported_csvs`を検索すると使い方がわかる。
+
+# テストについて
 
 テストでは実際にデータベースを作成している。
 デフォルトでは全部は実行しないが、master log fileをおき、かつ環境変数`LOCAL_TEST`を設定することで、master log fileが必要な工程まで含めて実行できる。[^1]
 
 [^1]: master log fileはgitには入れたくないので、このような形態をとっている。
 
-## API
+# 新しいQAQCキャンペーン時に更新すべき内容
+
+- [`PSBoardDataBase.insert_qaqc_campaign_id`](@ref): キャンペーンの日時
+- [`PSBoardDataBase.get_campaign_id_from_run_id`](@ref): runidとの関係
+
+# API
 
 ```@index
 ```
@@ -22,7 +43,7 @@ CurrentModule = PSBoardDataBase
 Modules = [PSBoardDataBase]
 ```
 
-### `QaqcMasterLog`
+## `QaqcMasterLog`
 
 ```@autodocs
 Modules = [QaqcMasterLog]

src/import_data.jl

@@ -1,3 +1,8 @@
+"""
+    insert_qaqc_campaign_id(db::SQLite.DB)
+
+Fill qaqc_campaigns table in `db`.
+"""
 function insert_qaqc_campaign_id(db::SQLite.DB)
     campaigns = [1, 2, 3]
     dates = [
@@ -22,6 +27,11 @@ function insert_qaqc_campaign_id(db::SQLite.DB)
     nothing
 end
 
+"""
+    insert_qaqc_positions(db::SQLite.DB)
+
+Fill qaqc_positions table in `db`.
+"""
 function insert_qaqc_positions(db::SQLite.DB)
     stmt = DBInterface.prepare(
         db,
@@ -49,7 +59,12 @@ function insert_qaqc_positions(db::SQLite.DB)
 end
 
 """
+    prepare_single_result_df(single_result_table::DataFrame)
+
 Common preprocess(format) function for single result table.
+
+# Detail
+- convert `timestamp` to [`DateTime`](@extref Dates.DateTime)
 """
 function prepare_single_result_df(single_result_table::DataFrame)
     df = copy(single_result_table, copycols = true)
@@ -66,6 +81,8 @@ function prepare_single_result_df(single_result_table::DataFrame)
 end
 
 """
+    prepare_runlist_df(runlist_table::DataFrame)
+
 Common preprocess(format) function for runlist table.
 """
 function prepare_runlist_df(runlist_table::DataFrame)
@@ -73,7 +90,10 @@ function prepare_runlist_df(runlist_table::DataFrame)
 end
 
 """
+    add_psboard_ids(db::SQLite.DB, single_result_table::DataFrame)
+
 Add PS Board IDs from single test result table.
+Assume that all PS Boards are included in `single_result_table`.
 """
 function add_psboard_ids(db::SQLite.DB, single_result_table::DataFrame)
     df = combine(groupby(single_result_table, :motherboard_id)) do df
@@ -98,7 +118,12 @@ function add_psboard_ids(db::SQLite.DB, single_result_table::DataFrame)
     nothing
 end
 
-function add_qaqc_runlist(db::SQLite.DB, runlist_table::DataFrame)
+"""
+    add_qaqc_runlist_from_runlist(db::SQLite.DB, runlist_table::DataFrame)
+
+Add QAQC runs to `qaqc_runs` table in `db` from RUNLIST csv.
+"""
+function add_qaqc_runlist_from_runlist(db::SQLite.DB, runlist_table::DataFrame)
     stmt_insert_runid = DBInterface.prepare(
         db,
         sql"""
@@ -130,16 +155,34 @@ function add_qaqc_runlist(db::SQLite.DB, runlist_table::DataFrame)
     nothing
 end
 
+"""
+    get_campaign_id_from_run_id(runid::Integer)
+"""
 function get_campaign_id_from_run_id(runid::Integer)
     if runid < 63
         1
     elseif runid < 98
         2
-    else
+    elseif runid < 169
         3
+    else
+        @error "Fix this function"
+        DomainError("runid $(runid) is not registered to the software")
     end
 end
 
+"""
+    add_qaqc_single_result(
+        db::SQLite.DB,
+        single_result_table::DataFrame,
+        runlist_table::DataFrame,
+    ) -> nothing
+
+Fill `qaqc_single_run_results` in `db` from single result table DataFrame.
+Additionaly, it
+1. automatically add `runid` if it's not in `qaqc_runs` table in `db`.
+2. automatically update fields in `qaqc_runs` table.
+"""
 function add_qaqc_single_result(
     db::SQLite.DB,
     single_result_table::DataFrame,
@@ -303,6 +346,12 @@ function add_qaqc_single_result(
     nothing
 end
 
+"""
+    prepare_dispatch_table(raw_dispatch_table::DataFrame)::DataFrame
+
+Format `qaqc_dispatch` DataFrame from exported CSV.
+Used in [`add_qaqc_dispatch`](@ref).
+"""
 function prepare_dispatch_table(raw_dispatch_table::DataFrame)::DataFrame
     df = copy(raw_dispatch_table, copycols = true)
     transform!(
@@ -334,6 +383,11 @@ function prepare_dispatch_table(raw_dispatch_table::DataFrame)::DataFrame
     df
 end
 
+"""
+    add_qaqc_dispatch(db::SQLite.DB, dispatch_table::DataFrame)
+
+Fill `qaqc_dispatch` table in `db` from `dispatch_table`.
+"""
 function add_qaqc_dispatch(db::SQLite.DB, dispatch_table::DataFrame)
     dispatch_table = prepare_dispatch_table(dispatch_table)
 
@@ -355,6 +409,8 @@ function add_qaqc_dispatch(db::SQLite.DB, dispatch_table::DataFrame)
 end
 
 """
+    add_qaqc_runlist_from_masterlogs(db::SQLite.DB, logs_dir::AbstractString) -> nothing
+
 Add qaqc run list from master log files in `logs_dir`.
 Currently, it adds long runs and run with id 20-23 only (since normal runs are added from single run results table).
 """
@@ -439,6 +495,18 @@ function add_qaqc_runlist_from_masterlogs(db::SQLite.DB, logs_dir::AbstractStrin
     nothing
 end
 
+"""
+    prepare_100test_table(table::DataFrame)::DataFrame
+
+Format 100test result `table` from exported CSV.
+Used in [`add_qaqc_100test_result`](@ref).
+
+# Detail
+- Format `motherboard ID`s
+    - `PS00xxxx` -> `Int64(xxxx)`
+    - `xxxx` -> `Int64(xxxx)`
+- For `psbid == 484` and `runid == 115` results, make all result fields to `missing` since they contain abnormal strings.
+"""
 function prepare_100test_table(table::DataFrame)::DataFrame
     df = copy(table, copycols = true)
 
@@ -464,6 +532,18 @@ function prepare_100test_table(table::DataFrame)::DataFrame
     df
 end
 
+"""
+    get_num_tests_for_extra_runs(runid::Int64)
+
+Get number of tests for extra QAQC runs.
+They are usually 100.
+
+Current abnormal runs:
+
+| runid | # of runs |
+|-------|-----------|
+|     99|        246|
+"""
 function get_num_tests_for_extra_runs(runid::Int64)
     if runid == 99
         246
@@ -472,6 +552,15 @@ function get_num_tests_for_extra_runs(runid::Int64)
     end
 end
 
+"""
+    add_qaqc_100test_result(db::SQLite.DB, table::DataFrame) -> nothing
+
+Fill `qaqc_extra_run_results` table in `db` from `table` DataFrame,
+which is converted from a raw exported CSV.
+
+# Detail
+- skips psboards in `resistance_test_passed` with `passed == false`
+"""
 function add_qaqc_100test_result(db::SQLite.DB, table::DataFrame)
     position_id_map =
         ["B-$i-$j" for i in 0:1 for j in 1:9] |> enumerate .|> (x -> begin
@@ -543,7 +632,6 @@ function add_qaqc_100test_result(db::SQLite.DB, table::DataFrame)
     )
 
     for row in eachrow(table)
-        # TODO: get runid from master log file
         if DBInterface.execute(stmt_search_runid, (; runid = row.runid)) |> isempty
             # search for resistance error
             if !isempty(
@@ -554,6 +642,7 @@ function add_qaqc_100test_result(db::SQLite.DB, table::DataFrame)
             )
                 continue
             end
+            error("Runid $(row.runid) not found in `qaqc_runs` table.")
         end
 
         DBInterface.execute(

src/parse_qaqc_master_log.jl

@@ -1,3 +1,6 @@
+"""
+Module for QAQC master log parser.
+"""
 module QaqcMasterLog
 
 using Dates
@@ -19,6 +22,8 @@ struct QaqcMasterLogMetadata
 end
 
 """
+    parse_master_log(logfile::AbstractString)
+
 Parse master log.
 If the `logfile` is empty, return `nothing`.
 """

test/runtests.jl

@@ -42,7 +42,7 @@ true || include("../src/PSBoardDataBase.jl")
         runlist_table = CSV.read("input/PS board QAQC Data Base - RUNLIST.csv", DataFrame)
 
         @test PSBoardDataBase.add_psboard_ids(db, single_result_df) |> isnothing
-        @test PSBoardDataBase.add_qaqc_runlist(db, runlist_table) |> isnothing
+        @test PSBoardDataBase.add_qaqc_runlist_from_runlist(db, runlist_table) |> isnothing
 
         @test PSBoardDataBase.add_qaqc_single_result(db, single_result_df, runlist_table) |>
               isnothing