docs: context and payload

packages/github_action_context/lib/src/context.dart

@@ -8,21 +8,46 @@ final context = Context();
 class Context {
   late WebhookPayload payload;
 
+  /// The name of the event that triggered the workflow.
   late String eventName;
+
+  /// The commit SHA that triggered the workflow.
   late String sha;
+
+  /// The ref that triggered the workflow.
   late String ref;
+
+  /// The workflow name.
   late String workflow;
+
+  /// The action name.
   late String action;
+
+  /// The username of the user or app that initiated the workflow.
   late String actor;
+
+  /// The job name.
   late String job;
+
+  /// The run number of the workflow.
   late int runNumber;
+
+  /// The run ID of the workflow.
   late int runId;
+
+  /// The URL of the GitHub API.
   late String apiUrl;
+
+  /// The URL of the GitHub server.
   late String serverUrl;
+
+  /// The URL of the GitHub GraphQL API.
   late String graphqlUrl;
 
+  /// Retrieves the environment variables.
   Map<String, String> get env => Platform.environment;
 
+  /// Constructs a new instance of the Context class.
   Context() {
     if (env.containsKey('GITHUB_EVENT_PATH')) {
       String eventPath = env['GITHUB_EVENT_PATH']!;
@@ -49,6 +74,7 @@ class Context {
         env.stringValue('GITHUB_GRAPHQL_URL', 'https://api.github.com/graphql');
   }
 
+  /// Gets the information about the issue.
   IssueInfo get issue {
     final payload = this.payload;
 
@@ -69,6 +95,7 @@ class Context {
     );
   }
 
+  /// Gets the information about the repository.
   RepoInfo get repo {
     if (env.containsKey('GITHUB_REPOSITORY')) {
       final repoParts = env['GITHUB_REPOSITORY']!.split('/');
@@ -87,29 +114,46 @@ class Context {
   }
 }
 
+/// A class representing information about an issue.
 class IssueInfo {
+  /// The owner of the repository.
   final String owner;
+
+  /// The repository name
   final String repo;
+
+  /// The issue number.
   final int? number;
 
+  /// Constructs a new instance of the IssueInfo class.
   IssueInfo({
     required this.owner,
     required this.repo,
     this.number,
   });
 }
 
+/// A class representing information about a repository.
 class RepoInfo {
+  /// The owner of the repository.
   final String owner;
+
+  /// The repository name.
   final String repo;
 
+  /// Constructs a new instance of the RepoInfo class.
   RepoInfo({
     required this.owner,
     required this.repo,
   });
 }
 
+/// Extension methods for the Map<String, String> class.
 extension _PlatformExt on Map<String, String> {
+  /// Retrieves the value associated with the given key as a string.
+  ///
+  /// If the key is not found, [defaultValue] is returned.
+  /// If [defaultValue] is not provided and the key is not found, an exception is thrown.
   String stringValue(String key, [String? defaultValue]) {
     final result = this[key] ?? defaultValue;
     if (result == null) {
@@ -118,6 +162,12 @@ extension _PlatformExt on Map<String, String> {
     return result;
   }
 
+  /// Retrieves the value associated with the given key as an integer.
+  ///
+  /// If the key is not found or the value cannot be parsed as an integer,
+  /// [defaultValue] is returned (if provided).
+  /// If [defaultValue] is not provided and the value cannot be parsed as an integer,
+  /// an exception is thrown.
   int intValue(String key, [int? defaultValue]) {
     try {
       return int.parse(this[key]!);

packages/github_action_context/lib/src/interface.dart

@@ -1,6 +1,7 @@
 import 'dart:collection';
 import 'dart:convert';
 
+/// Represents a base item with map-like behavior.
 class _BaseItem with MapMixin<dynamic, dynamic> {
   final Map innerMap;
 
@@ -29,6 +30,7 @@ class _BaseItem with MapMixin<dynamic, dynamic> {
     return innerMap.remove(key);
   }
 
+  /// Converts the inner map to a JSON string.
   String toJson() {
     return json.encode(innerMap);
   }
@@ -39,12 +41,21 @@ class _BaseItem with MapMixin<dynamic, dynamic> {
   }
 }
 
+/// Represents the payload repository information.
 class PayloadRepository extends _BaseItem {
+  /// The full name of the repository.
   String? fullName;
+
+  /// The name of the repository.
   String name;
+
+  /// The owner of the repository.
   Owner owner;
+
+  /// The URL of the repository.
   String? htmlUrl;
 
+  /// Constructs a new instance of the PayloadRepository class.
   PayloadRepository(
     super.innerMap, {
     this.fullName,
@@ -53,6 +64,7 @@ class PayloadRepository extends _BaseItem {
     this.htmlUrl,
   });
 
+  /// Creates a PayloadRepository instance from a JSON map.
   static PayloadRepository? fromJson(Map? json) {
     if (json == null) {
       return null;
@@ -67,16 +79,22 @@ class PayloadRepository extends _BaseItem {
   }
 }
 
+/// Represents the owner information.
 class Owner extends _BaseItem {
+  /// The login name of the owner.
   String login;
+
+  /// The name of the owner.
   String? name;
 
+  /// Constructs a new instance of the Owner class.
   Owner(
     super.innerMap, {
     required this.login,
     this.name,
   });
 
+  /// Creates an Owner instance from a JSON map.
   factory Owner.fromJson(Map json) {
     return Owner(
       json,
@@ -86,48 +104,27 @@ class Owner extends _BaseItem {
   }
 }
 
-// export interface WebhookPayload {
-//   [key: string]: any
-//   repository?: PayloadRepository
-//   issue?: {
-//     [key: string]: any
-//     number: number
-//     html_url?: string
-//     body?: string
-//   }
-//   pull_request?: {
-//     [key: string]: any
-//     number: number
-//     html_url?: string
-//     body?: string
-//   }
-//   sender?: {
-//     [key: string]: any
-//     type: string
-//   }
-//   action?: string
-//   installation?: {
-//     id: number
-//     [key: string]: any
-//   }
-//   comment?: {
-//     id: number
-//     [key: string]: any
-//   }
-// }
+/// Represents an issue.
 
 class Issue extends _BaseItem {
+  /// The issue number.
   int? number;
+
+  /// The URL of the issue.
   String? htmlUrl;
+
+  /// The body of the issue.
   String? body;
 
+  /// Constructs a new instance of the Issue class.
   Issue(
     super.innerMap, {
     this.number,
     this.htmlUrl,
     this.body,
   });
 
+  /// Creates an Issue instance from a JSON map.
   static Issue? fromJson(Map? json) {
     if (json == null) {
       return null;
@@ -141,14 +138,19 @@ class Issue extends _BaseItem {
   }
 }
 
+/// Represents the sender information.
+
 class Sender extends _BaseItem {
+  /// The type of the sender.
   String? type;
 
+  /// Constructs a new instance of the Sender class.
   Sender(
     super.innerMap, {
     this.type,
   });
 
+  /// Creates a Sender instance from a JSON map.
   static Sender? fromJson(Map? json) {
     if (json == null) {
       return null;
@@ -160,7 +162,10 @@ class Sender extends _BaseItem {
   }
 }
 
+/// Represents an item with an ID.
+
 class _IdItem extends _BaseItem {
+  /// The ID of the item.
   int? id;
 
   _IdItem(
@@ -169,12 +174,15 @@ class _IdItem extends _BaseItem {
   });
 }
 
+/// Represents an installation.
+
 class Installation extends _IdItem {
   Installation(
     super.innerMap, {
     super.id,
   });
 
+  /// Creates an Installation instance from a JSON map.
   static Installation? fromJson(Map? json) {
     if (json == null) {
       return null;
@@ -186,12 +194,15 @@ class Installation extends _IdItem {
   }
 }
 
+/// Represents a comment.
+
 class Comment extends _IdItem {
   Comment(
     super.innerMap, {
     super.id,
   });
 
+  /// Creates a Comment instance from a JSON map.
   static Comment? fromJson(Map? json) {
     if (json == null) {
       return null;
@@ -203,15 +214,31 @@ class Comment extends _IdItem {
   }
 }
 
+/// Represents the webhook payload.
+
 class WebhookPayload extends _BaseItem {
+  /// The payload repository information.
   PayloadRepository? repository;
+
+  /// The issue information.
   Issue? issue;
+
+  /// The pull request information.
   Issue? pullRequest;
+
+  /// The sender information.
   Sender? sender;
+
+  /// The action name.
   String? action;
+
+  /// The installation information.
   Installation? installation;
+
+  /// The comment information.
   Comment? comment;
 
+  /// Constructs a new instance of the WebhookPayload class.
   WebhookPayload(
     super.innerMap, {
     this.repository,
@@ -223,6 +250,7 @@ class WebhookPayload extends _BaseItem {
     this.comment,
   });
 
+  /// Creates a WebhookPayload instance from a JSON map.
   static WebhookPayload fromJson(Map json) {
     return WebhookPayload(
       json,