Skip to content

Commit 0c945cd

Browse files
shimomoshimomo
committed
docs: update PHPDoc comments
1 parent 318df18 commit 0c945cd

File tree

6 files changed

+92
-209
lines changed

6 files changed

+92
-209
lines changed

‎src/ProgramScraper.php‎

Lines changed: 16 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -8,73 +8,43 @@
88
use Carbon\CarbonInterface;
99

1010
/**
11+
* @psalm-import-type ScrapedStadiumRaces from ScraperInterface
12+
*
1113
* @author shimomo
1214
*/
1315
final class ProgramScraper
1416
{
1517
/**
16-
* @param \BOA\Programs\ScraperInterface $scraper
18+
* @psalm-param \BOA\Programs\ScraperInterface $scraper
19+
*
20+
* @param \BOA\Programs\ScraperInterface $scraper
1721
*/
1822
public function __construct(private readonly ScraperInterface $scraper)
1923
{
2024
//
2125
}
2226

2327
/**
24-
* @phpstan-type ScrapedRace array<non-empty-string, array<int, string|float|int>|string|int>
25-
* @phpstan-type ScrapedRaces array<int, ScrapedRace>
26-
* @phpstan-type NormalizedBoat array{
27-
* racer_boat_number: int,
28-
* racer_name: string,
29-
* racer_number: int,
30-
* racer_class_number: int,
31-
* racer_branch_number: int,
32-
* racer_birthplace_number: int,
33-
* racer_age: int,
34-
* racer_weight: float|int,
35-
* racer_flying_count: int,
36-
* racer_late_count: int,
37-
* racer_average_start_timing: float|int,
38-
* racer_national_top_1_percent: float|int,
39-
* racer_national_top_2_percent: float|int,
40-
* racer_national_top_3_percent: float|int,
41-
* racer_local_top_1_percent: float|int,
42-
* racer_local_top_2_percent: float|int,
43-
* racer_local_top_3_percent: float|int,
44-
* racer_assigned_motor_number: int,
45-
* racer_assigned_motor_top_2_percent: float|int,
46-
* racer_assigned_motor_top_3_percent: float|int,
47-
* racer_assigned_boat_number: int,
48-
* racer_assigned_boat_top_2_percent: float|int,
49-
* racer_assigned_boat_top_3_percent: float|int
50-
* }
51-
* @phpstan-type NormalizedRace array{
52-
* race_date: string,
53-
* race_stadium_number: int,
54-
* race_number: int,
55-
* race_closed_at: string,
56-
* race_grade_number: int,
57-
* race_title: string,
58-
* race_subtitle: string,
59-
* race_distance: int,
60-
* boats: array<int, NormalizedBoat>
61-
* }
62-
* @phpstan-type NormalizedRaces array<int, NormalizedRace>
28+
* @psalm-param \Carbon\CarbonInterface|string $date
29+
* @psalm-return ScrapedStadiumRaces
6330
*
64-
* @param \Carbon\CarbonInterface|string $date
65-
* @return array<int, NormalizedRaces>
31+
* @param \Carbon\CarbonInterface|string $date
32+
* @return array
6633
*/
6734
public function scrape(CarbonInterface|string $date = 'today'): array
6835
{
6936
$date = Carbon::parse($date, 'Asia/Tokyo');
70-
/** @var array<int, ScrapedRaces> $programs */
37+
/** @psalm-var ScrapedStadiumRaces $programs */
7138
$programs = $this->scraper->scrapePrograms($date);
7239
return $this->normalize($programs);
7340
}
7441

7542
/**
76-
* @param array<int, ScrapedRaces> $programs
77-
* @return array<int, NormalizedRaces>
43+
* @psalm-param ScrapedStadiumRaces $programs
44+
* @psalm-return ScrapedStadiumRaces
45+
*
46+
* @param array $programs
47+
* @return array
7848
*/
7949
private function normalize(array $programs): array
8050
{
@@ -89,7 +59,7 @@ private function normalize(array $programs): array
8959
}
9060
}
9161

92-
/** @var array<int, NormalizedRaces> */
62+
/** @psalm-var ScrapedStadiumRaces */
9363
return $newPrograms;
9464
}
9565
}

‎src/ProgramStorage.php‎

Lines changed: 7 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,51 +5,19 @@
55
namespace BOA\Programs;
66

77
/**
8+
* @psalm-import-type ScrapedStadiumRaces from ScraperInterface
9+
*
810
* @author shimomo
911
*/
1012
final class ProgramStorage
1113
{
1214
/**
13-
* @phpstan-type NormalizedBoat array{
14-
* racer_boat_number: int,
15-
* racer_name: string,
16-
* racer_number: int,
17-
* racer_class_number: int,
18-
* racer_branch_number: int,
19-
* racer_birthplace_number: int,
20-
* racer_age: int,
21-
* racer_weight: float|int,
22-
* racer_flying_count: int,
23-
* racer_late_count: int,
24-
* racer_average_start_timing: float|int,
25-
* racer_national_top_1_percent: float|int,
26-
* racer_national_top_2_percent: float|int,
27-
* racer_national_top_3_percent: float|int,
28-
* racer_local_top_1_percent: float|int,
29-
* racer_local_top_2_percent: float|int,
30-
* racer_local_top_3_percent: float|int,
31-
* racer_assigned_motor_number: int,
32-
* racer_assigned_motor_top_2_percent: float|int,
33-
* racer_assigned_motor_top_3_percent: float|int,
34-
* racer_assigned_boat_number: int,
35-
* racer_assigned_boat_top_2_percent: float|int,
36-
* racer_assigned_boat_top_3_percent: float|int
37-
* }
38-
* @phpstan-type NormalizedRace array{
39-
* race_date: string,
40-
* race_stadium_number: int,
41-
* race_number: int,
42-
* race_closed_at: string,
43-
* race_grade_number: int,
44-
* race_title: string,
45-
* race_subtitle: string,
46-
* race_distance: int,
47-
* boats: array<int, NormalizedBoat>
48-
* }
49-
* @phpstan-type NormalizedRaces array<int, NormalizedRace>
15+
* @psalm-param ScrapedStadiumRaces $programs
16+
* @psalm-param non-empty-string $path
17+
* @psalm-return void
5018
*
51-
* @param array<int, NormalizedRaces> $programs
52-
* @param non-empty-string $path
19+
* @param array $programs
20+
* @param string $path
5321
* @return void
5422
* @throws \RuntimeException
5523
*/

‎src/ScraperAdapter.php‎

Lines changed: 9 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -8,60 +8,28 @@
88
use Carbon\CarbonInterface;
99

1010
/**
11+
* @psalm-import-type ScrapedStadiumRaces from ScraperInterface
12+
*
1113
* @author shimomo
1214
*/
1315
final class ScraperAdapter implements ScraperInterface
1416
{
1517
/**
16-
* @param \BVP\Scraper\Scraper $scraper
18+
* @psalm-param \BVP\Scraper\Scraper $scraper
19+
*
20+
* @param \BVP\Scraper\Scraper $scraper
1721
*/
1822
public function __construct(private readonly Scraper $scraper)
1923
{
2024
//
2125
}
2226

2327
/**
24-
* @psalm-type ScrapedBoat = array{
25-
* racer_boat_number: int,
26-
* racer_name: string,
27-
* racer_number: int,
28-
* racer_class_number: int,
29-
* racer_branch_number: int,
30-
* racer_birthplace_number: int,
31-
* racer_age: int,
32-
* racer_weight: float,
33-
* racer_flying_count: int,
34-
* racer_late_count: int,
35-
* racer_average_start_timing: float,
36-
* racer_national_top_1_percent: float,
37-
* racer_national_top_2_percent: float,
38-
* racer_national_top_3_percent: float,
39-
* racer_local_top_1_percent: float,
40-
* racer_local_top_2_percent: float,
41-
* racer_local_top_3_percent: float,
42-
* racer_assigned_motor_number: int,
43-
* racer_assigned_motor_top_2_percent: float,
44-
* racer_assigned_motor_top_3_percent: float,
45-
* racer_assigned_boat_number: int,
46-
* racer_assigned_boat_top_2_percent: float,
47-
* racer_assigned_boat_top_3_percent: float
48-
* }
49-
* @psalm-type ScrapedRace = array{
50-
* race_date: string,
51-
* race_stadium_number: int,
52-
* race_number: int,
53-
* race_closed_at: string,
54-
* race_grade_number: int,
55-
* race_title: string,
56-
* race_subtitle: string,
57-
* race_distance: int,
58-
* boats: array<int, ScrapedBoat>
59-
* }
60-
* @psalm-type ScrapedRaces = array<int, ScrapedRace>
61-
* @psalm-type ScrapedStadiumRaces = array<int, ScrapedRaces>
28+
* @psalm-param \Carbon\CarbonInterface $date
29+
* @psalm-return ScrapedStadiumRaces
6230
*
63-
* @param \Carbon\CarbonInterface $date
64-
* @return ScrapedStadiumRaces
31+
* @param \Carbon\CarbonInterface $date
32+
* @return array
6533
*/
6634
#[\Override]
6735
public function scrapePrograms(CarbonInterface $date): array

‎src/ScraperInterface.php‎

Lines changed: 43 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -7,52 +7,55 @@
77
use Carbon\CarbonInterface;
88

99
/**
10+
* @psalm-type ScrapedBoat = array{
11+
* racer_boat_number: int,
12+
* racer_name: string,
13+
* racer_number: int,
14+
* racer_class_number: int,
15+
* racer_branch_number: int,
16+
* racer_birthplace_number: int,
17+
* racer_age: int,
18+
* racer_weight: float,
19+
* racer_flying_count: int,
20+
* racer_late_count: int,
21+
* racer_average_start_timing: float,
22+
* racer_national_top_1_percent: float,
23+
* racer_national_top_2_percent: float,
24+
* racer_national_top_3_percent: float,
25+
* racer_local_top_1_percent: float,
26+
* racer_local_top_2_percent: float,
27+
* racer_local_top_3_percent: float,
28+
* racer_assigned_motor_number: int,
29+
* racer_assigned_motor_top_2_percent: float,
30+
* racer_assigned_motor_top_3_percent: float,
31+
* racer_assigned_boat_number: int,
32+
* racer_assigned_boat_top_2_percent: float,
33+
* racer_assigned_boat_top_3_percent: float
34+
* }
35+
* @psalm-type ScrapedRace = array{
36+
* race_date: string,
37+
* race_stadium_number: int,
38+
* race_number: int,
39+
* race_closed_at: string,
40+
* race_grade_number: int,
41+
* race_title: string,
42+
* race_subtitle: string,
43+
* race_distance: int,
44+
* boats: array<int, ScrapedBoat>
45+
* }
46+
* @psalm-type ScrapedRaces = array<int, ScrapedRace>
47+
* @psalm-type ScrapedStadiumRaces = array<int, ScrapedRaces>
48+
*
1049
* @author shimomo
1150
*/
1251
interface ScraperInterface
1352
{
1453
/**
15-
* @psalm-type ScrapedBoat = array{
16-
* racer_boat_number: int,
17-
* racer_name: string,
18-
* racer_number: int,
19-
* racer_class_number: int,
20-
* racer_branch_number: int,
21-
* racer_birthplace_number: int,
22-
* racer_age: int,
23-
* racer_weight: float,
24-
* racer_flying_count: int,
25-
* racer_late_count: int,
26-
* racer_average_start_timing: float,
27-
* racer_national_top_1_percent: float,
28-
* racer_national_top_2_percent: float,
29-
* racer_national_top_3_percent: float,
30-
* racer_local_top_1_percent: float,
31-
* racer_local_top_2_percent: float,
32-
* racer_local_top_3_percent: float,
33-
* racer_assigned_motor_number: int,
34-
* racer_assigned_motor_top_2_percent: float,
35-
* racer_assigned_motor_top_3_percent: float,
36-
* racer_assigned_boat_number: int,
37-
* racer_assigned_boat_top_2_percent: float,
38-
* racer_assigned_boat_top_3_percent: float
39-
* }
40-
* @psalm-type ScrapedRace = array{
41-
* race_date: string,
42-
* race_stadium_number: int,
43-
* race_number: int,
44-
* race_closed_at: string,
45-
* race_grade_number: int,
46-
* race_title: string,
47-
* race_subtitle: string,
48-
* race_distance: int,
49-
* boats: array<int, ScrapedBoat>
50-
* }
51-
* @psalm-type ScrapedRaces = array<int, ScrapedRace>
52-
* @psalm-type ScrapedStadiumRaces = array<int, ScrapedRaces>
54+
* @psalm-param \Carbon\CarbonInterface $date
55+
* @psalm-return ScrapedStadiumRaces
5356
*
54-
* @param \Carbon\CarbonInterface $date
55-
* @return ScrapedStadiumRaces
57+
* @param \Carbon\CarbonInterface $date
58+
* @return array
5659
*/
5760
public function scrapePrograms(CarbonInterface $date): array;
5861
}

‎tests/ProgramScraperTest.php‎

Lines changed: 8 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,15 @@
1010
use PHPUnit\Framework\TestCase;
1111

1212
/**
13+
* @psalm-import-type ScrapedStadiumRaces from ScraperInterface
14+
*
1315
* @author shimomo
1416
*/
1517
final class ProgramScraperTest extends Testcase
1618
{
1719
/**
18-
* @param \Carbon\CarbonInterface|string $date
20+
* @psalm-return void
21+
*
1922
* @return void
2023
*/
2124
public function testScrape(): void
@@ -32,48 +35,11 @@ public function testScrape(): void
3235
}
3336

3437
/**
35-
* @psalm-type NormalizedBoat array{
36-
* racer_boat_number: int,
37-
* racer_name: string,
38-
* racer_number: int,
39-
* racer_class_number: int,
40-
* racer_branch_number: int,
41-
* racer_birthplace_number: int,
42-
* racer_age: int,
43-
* racer_weight: int|float,
44-
* racer_flying_count: int,
45-
* racer_late_count: int,
46-
* racer_average_start_timing: float,
47-
* racer_national_top_1_percent: float,
48-
* racer_national_top_2_percent: float,
49-
* racer_national_top_3_percent: float,
50-
* racer_local_top_1_percent: float,
51-
* racer_local_top_2_percent: float,
52-
* racer_local_top_3_percent: float,
53-
* racer_assigned_motor_number: int,
54-
* racer_assigned_motor_top_2_percent: float,
55-
* racer_assigned_motor_top_3_percent: float,
56-
* racer_assigned_boat_number: int,
57-
* racer_assigned_boat_top_2_percent: float,
58-
* racer_assigned_boat_top_3_percent: float
59-
* }
60-
*
61-
* @psalm-type NormalizedRace array{
62-
* race_date: string,
63-
* race_stadium_number: int,
64-
* race_number: int,
65-
* race_closed_at: string,
66-
* race_grade_number: int,
67-
* race_title: string,
68-
* race_subtitle: string,
69-
* race_distance: int,
70-
* boats: array<int, NormalizedBoat>
71-
* }
72-
*
73-
* @psalm-type NormalizedRaces array<int, NormalizedRace>
38+
* @psalm-param int $keyIndex
39+
* @psalm-return ScrapedStadiumRaces
7440
*
75-
* @param int $keyIndex
76-
* @return NormalizedRaces
41+
* @param int $keyIndex
42+
* @return array
7743
*/
7844
private function testScrapeData(int $keyIndex): array
7945
{

0 commit comments

Comments
 (0)