Merge pull request #970 from golemfactory/docs/JST-925/typedocs

docs: fixed comments and references for Typedoc

src/activity/activity.ts

@@ -11,7 +11,7 @@ export enum ActivityStateEnum {
   Unknown = "Unknown",
 }
 
-type ActivityUsageInfo = {
+export type ActivityUsageInfo = {
   currentUsage?: number[];
   timestamp: number;
 };

src/activity/results.ts

@@ -80,11 +80,11 @@ export interface RuntimeEventKind {
   finished?: RuntimeEventFinished;
 }
 
-interface RuntimeEventStarted {
+export interface RuntimeEventStarted {
   command: object;
 }
 
-interface RuntimeEventFinished {
+export interface RuntimeEventFinished {
   // Reason for disable: That's something what yagna returns from its api
   // eslint-disable-next-line @typescript-eslint/naming-convention
   return_code: number;

src/activity/script/command.ts

@@ -80,9 +80,9 @@ export type CaptureMode =
   | { atEnd: { part?: CapturePart; format?: CaptureFormat } }
   | { stream: { limit?: number; format?: CaptureFormat } };
 
-type CapturePart = { head: number } | { tail: number } | { headTail: number };
+export type CapturePart = { head: number } | { tail: number } | { headTail: number };
 
-type CaptureFormat = "string" | "binary";
+export type CaptureFormat = "string" | "binary";
 
 export class Run extends Command {
   constructor(cmd: string, args?: string[] | null, env?: object | null, capture?: Capture) {
@@ -135,9 +135,6 @@ export class UploadFile extends Transfer {
   }
 }
 
-/**
- * @category Mid-level
- */
 export class UploadData extends Transfer {
   constructor(
     private storageProvider: StorageProvider,
@@ -178,9 +175,6 @@ export class DownloadFile extends Transfer {
   }
 }
 
-/**
- * @category Mid-level
- */
 export class DownloadData extends Transfer<Uint8Array> {
   private chunks: Uint8Array[] = [];
 

src/activity/work/process.ts

@@ -9,7 +9,7 @@ const DEFAULTS = {
 };
 
 /**
- * RemoteProcess class representing the process spawned on the provider by {@link WorkContext.runAndStream}
+ * RemoteProcess class representing the process spawned on the provider by {@link activity/work/work.WorkContext.runAndStream}
  */
 export class RemoteProcess {
   /**

src/experimental/deployment/builder.ts

@@ -4,7 +4,7 @@ import { Deployment, DeploymentComponents } from "./deployment";
 import { GolemNetwork, MarketOrderSpec } from "../../golem-network";
 import { validateDeployment } from "./validate-deployment";
 
-interface DeploymentOptions {
+export interface DeploymentOptions {
   replicas: number | { min: number; max: number };
   network?: string;
 }

src/experimental/job/job.ts

@@ -86,10 +86,10 @@ export class Job<Output = unknown> {
 
   /**
    * Run your worker function on the Golem Network. This method will synchronously initialize all internal services and validate the job options. The work itself will be run asynchronously in the background.
-   * You can use the {@link Job.events} event emitter to listen for state changes.
-   * You can also use {@link Job.waitForResult} to wait for the job to finish and get the results.
-   * If you want to cancel the job, use {@link Job.cancel}.
-   * If you want to run multiple jobs in parallel, you can use {@link GolemNetwork.createJob} to create multiple jobs and run them in parallel.
+   * You can use the {@link experimental/job/job.Job.events} event emitter to listen for state changes.
+   * You can also use {@link experimental/job/job.Job.waitForResult} to wait for the job to finish and get the results.
+   * If you want to cancel the job, use {@link experimental/job/job.Job.cancel}.
+   * If you want to run multiple jobs in parallel, you can use {@link experimental/job/job_manager.JobManager.createJob} to create multiple jobs and run them in parallel.
    *
    * @param workOnGolem - Your worker function that will be run on the Golem Network.
    */

src/experimental/job/job_manager.ts

@@ -54,7 +54,7 @@ export class JobManager {
 
   /**
    * Create a new job and add it to the list of jobs managed by this instance.
-   * This method does not start any work on the network, use {@link Job.startWork} for that.
+   * This method does not start any work on the network, use {@link experimental/job/job.Job.startWork} for that.
    *
    * @param order
    */

src/golem-network/golem-network.ts

@@ -43,7 +43,7 @@ import { IProposalRepository } from "../market/proposal";
  * Instance of an object or a factory function that you can call `new` on.
  * Optionally you can provide constructor arguments.
  */
-type InstanceOrFactory<TargetInterface, ConstructorArgs extends unknown[] = never[]> =
+export type InstanceOrFactory<TargetInterface, ConstructorArgs extends unknown[] = never[]> =
   | TargetInterface
   | { new (...args: ConstructorArgs): TargetInterface };
 
@@ -133,7 +133,7 @@ export interface GolemNetworkEvents {
   disconnected: () => void;
 }
 
-interface ManyOfOptions {
+export interface ManyOfOptions {
   concurrency: Concurrency;
   order: MarketOrderSpec;
 }

src/market/agreement/agreement.ts

@@ -35,7 +35,7 @@ export class Agreement {
   /**
    * @param id
    * @param model
-   * @param paymentPlatform
+   * @param demand
    */
   constructor(
     public readonly id: string,

src/market/demand/demand-body-builder.ts

@@ -26,7 +26,7 @@ type DemandConstraint = {
  * Data structure that represents details of the body for a demand subscription request
  *
  * This type belongs to our domain (use case layer), and will later be "serialized" to the body that's sent to
- * Yagna. You should consider this as a "draft of the demand", that can be finalized by one of the {@link MarketApi}
+ * Yagna. You should consider this as a "draft of the demand", that can be finalized by one of the {@link market/api.IMarketApi}
  * implementations.
  */
 export type DemandBodyPrototype = {

src/market/demand/options.ts

@@ -3,7 +3,7 @@ import { RequireAtLeastOne } from "../../shared/utils/types";
 /**
  * Specifies a set of options related to computation resources that will be used to form the demand
  */
-type ResourceDemandOptions = {
+export type ResourceDemandOptions = {
   /** Minimum required memory to execute application GB */
   minMemGib: number;
   /** Minimum required disk storage to execute tasks in GB */
@@ -17,7 +17,7 @@ type ResourceDemandOptions = {
 /**
  * Specifies a set of options related to runtime configuration that will be used to form the demand
  */
-type RuntimeDemandOptions = {
+export type RuntimeDemandOptions = {
   /** Type of engine required: vm, wasm, vm-nvidia, etc... */
   engine: string;
 
@@ -28,7 +28,7 @@ type RuntimeDemandOptions = {
 /**
  * Specifies a set of options related to computation manifest that can be used to form the demand
  */
-type ManifestDemandOptions = {
+export type ManifestDemandOptions = {
   manifest: string;
   /** Signature of base64 encoded Computation Payload Manifest **/
   manifestSig: string;
@@ -41,7 +41,7 @@ type ManifestDemandOptions = {
 /**
  * Specifies a set of options related to the Golem VM Image (GVMI) that will be used to form the demand
  */
-type ImageDemandOptions = {
+export type ImageDemandOptions = {
   /**
    * If you want a provider to download the image from your local filesystem or
    * a different registry than the default one, you can provide the image url here.

src/market/market.module.ts

@@ -154,7 +154,8 @@ export interface MarketModule {
    * const agreement = await marketModule.signAgreementFromPool(draftProposalPool, signal); // throws TimeoutError if the operation takes longer than 10 seconds
    * ```
    * @param draftProposalPool - The pool of draft proposals to acquire from
-   * @param timeout - The timeout in milliseconds or an AbortSignal that will be used to cancel the operation
+   * @param agreementOptions - options used to sign the agreement such as expiration or waitingForApprovalTimeout
+   * @param signalOrTimeout - The timeout in milliseconds or an AbortSignal that will be used to cancel the operation
    */
   signAgreementFromPool(
     draftProposalPool: DraftOfferProposalPool,

src/market/proposal/proposal-properties.ts

@@ -14,20 +14,20 @@
  * @link https://github.com/golemfactory/golem-architecture/tree/master/standards Golem standards
  * @link https://github.com/golemfactory/golem-architecture/tree/master/gaps Golem Architecture Proposals
  */
-type GenericGolemProtocolPropertyType = Record<string, string | number | string[] | number[] | boolean>;
+export type GenericGolemProtocolPropertyType = Record<string, string | number | string[] | number[] | boolean>;
 /**
  * Properties defined by GAP-3
  *
  * @link https://github.com/golemfactory/golem-architecture/blob/master/gaps/gap-3_mid_agreement_payments/gap-3_mid_agreement_payments.md
  */
-type Gap3MidAgreementPaymentProps = {
+export type Gap3MidAgreementPaymentProps = {
   "golem.com.scheme.payu.debit-note.interval-sec?"?: number;
   "golem.com.scheme.payu.payment-timeout-sec?"?: number;
 };
 /**
  * @link https://github.com/golemfactory/golem-architecture/tree/master/standards/0-commons
  */
-type StandardCommonProps = {
+export type StandardCommonProps = {
   "golem.activity.caps.transfer.protocol": ("http" | "https" | "gftp")[];
   "golem.inf.cpu.architecture": string;
   "golem.inf.cpu.brand": string;
@@ -46,7 +46,7 @@ type StandardCommonProps = {
 /**
  * https://github.com/golemfactory/golem-architecture/blob/master/standards/2-service/srv.md
  */
-type StandardNodeProps = {
+export type StandardNodeProps = {
   "golem.node.id.name": string;
   /** @deprecated Do not rely on this, it's mentioned in the standard, but not implemented FIXME #yagna */
   "golem.node.geo.country_code"?: string;
@@ -55,7 +55,7 @@ type StandardNodeProps = {
 /**
  * @link https://github.com/golemfactory/golem-architecture/blob/master/standards/3-commercial/com.md
  */
-type StandardCommercialProps = {
+export type StandardCommercialProps = {
   "golem.com.payment.debit-notes.accept-timeout?": number;
   /** @example "erc20-polygon-glm" */
   "golem.com.payment.chosen-platform": string;
@@ -75,14 +75,14 @@ type StandardCommercialProps = {
 /**
  * @link https://github.com/golemfactory/golem-architecture/blob/master/standards/2-service/srv.md
  */
-type StandardServiceProps = {
+export type StandardServiceProps = {
   "golem.srv.caps.multi-activity": boolean;
 };
 
 /**
  * @link https://github.com/golemfactory/golem-architecture/blob/master/standards/2-service/srv/comp.md
  */
-type StandardComputationPlatformProps = {
+export type StandardComputationPlatformProps = {
   "golem.srv.comp.expiration": number;
   "golem.srv.comp.task_package": string;
 };

src/network/tcpProxy.ts

@@ -3,15 +3,15 @@ import { WebSocket } from "ws";
 import { EventEmitter } from "eventemitter3";
 import { defaultLogger, Logger } from "../shared/utils";
 
-interface TcpProxyEvents {
+export interface TcpProxyEvents {
   /** Raised when the proxy encounters any sort of error */
   error: (err: unknown) => void;
 }
 
 /**
  * Configuration required by the TcpProxy to work properly
  */
-interface TcpProxyOptions {
+export interface TcpProxyOptions {
   /**
    * The logger instance to use for logging
    */

src/payment/InvoiceProcessor.ts

@@ -30,14 +30,15 @@ export class InvoiceProcessor {
 
   /**
    * Collects invoices from the Yagna API until the limit is reached or there are no more invoices.
-   * @param after Only collect invoices that were created after this date.
-   * @param limit Maximum number of invoices to collect.
-   * @param statuses Only collect invoices with these statuses.
-   * @param providerIds Only collect invoices from these providers.
-   * @param minAmount Only collect invoices with an amount greater than or equal to this.
-   * @param maxAmount Only collect invoices with an amount less than or equal to this.
-   * @param providerWallets Only collect invoices from these provider wallets.
-   * @param paymentPlatforms Only collect invoices from these payment platforms.
+   * @param {Object} options - The parameters for collecting invoices.
+   * @param options.after Only collect invoices that were created after this date.
+   * @param options.limit Maximum number of invoices to collect.
+   * @param options.statuses Only collect invoices with these statuses.
+   * @param options.providerIds Only collect invoices from these providers.
+   * @param options.minAmount Only collect invoices with an amount greater than or equal to this.
+   * @param options.maxAmount Only collect invoices with an amount less than or equal to this.
+   * @param options.providerWallets Only collect invoices from these provider wallets.
+   * @param options.paymentPlatforms Only collect invoices from these payment platforms.
    *
    * @example
    * ```typescript

src/shared/utils/logger/defaultLogger.ts

@@ -1,7 +1,7 @@
 import debugLogger from "debug";
 import { Logger } from "./logger";
 
-type DefaultLoggerOptions = {
+export type DefaultLoggerOptions = {
   /**
    * Disables prefixing the root namespace with golem-js
    *

src/shared/yagna/event-reader.ts

@@ -24,7 +24,7 @@ export type CancellablePoll<T> = {
   cancel: () => Promise<void>;
 };
 
-type EventsFetcherWithCursor<T extends EventDTO> = (lastEventTimestamp: string) => Promise<T[]>;
+export type EventsFetcherWithCursor<T extends EventDTO> = (lastEventTimestamp: string) => Promise<T[]>;
 
 export class EventReader {
   public constructor(private readonly logger: Logger) {}

src/shared/yagna/yagnaApi.ts

@@ -44,7 +44,7 @@ export interface YagnaExeScriptObserver {
  * - implements an event reader that collects events from Yagna endpoints and allows subscribing to them as Observables
  *   for agreements, debit notes and invoices. These observables emit ya-ts-client types on outputs
  *
- * End users of the SDK should not use this class and make use of {@link GolemNetwork} instead. This class is designed for
+ * End users of the SDK should not use this class and make use of {@link golem-network/golem-network.GolemNetwork} instead. This class is designed for
  * SDK developers to use.
  */
 export class YagnaApi {

tsconfig.json

@@ -19,12 +19,12 @@
   },
   "typedocOptions": {
     "entryPoints": ["src"],
-    "exclude": ["**/*.spec.ts", "src/stats/*.ts"],
+    "exclude": ["**/*.spec.ts", "**/*.test.ts"],
     "entryPointStrategy": "expand",
     "out": "docs",
     "sort": "static-first",
     "excludePrivate": true,
-    "name": "JavaScript API reference",
+    "name": "Golem-JS API reference",
     "categorizeByGroup": false,
     "excludeExternals": true,
     "excludeInternal": true