Skip to content

Commit

Permalink
move hook documentation (and others) into code, improve documentation…
Browse files Browse the repository at this point in the history 
… components (#11381)

* move some docs to comments

* remove comments

* fix missing space

* add api_doc

* tweak in file generation

* build from docs branch

* switch docs branch back to `main`

* bump CI

* Enum & PropertyDetails

* WIP - see current state of `hooks.mdx`

* completely remove `query-options` and `query-result` mdx

* useMutation

* handle subscription docs

* better function signature

* more hooks

* fix up import

* chores

* formatting

* suppress tsdoc warning

* api explorer nitpicks

* support for @deprecated

* use prerendered markdown in comments
to prevent client-side parsing

* add propTypes

* apply prettier

* fixup

* also display interface details for slightly complex types

* heading styling, do not use h6

* since everywhere, styling, `link` defaults

* add grouping, create documentation interface

* `MutationOptionsDocumentation` interface

* api reports

* subscription options

* api repots

* prettier

* fix some references

* cleanup

* fix up SubHeading links

* don't add prefix to parameter properties

* allow property deep linking

* prettier

* more cleanup

* also add result documentation

* more doccomment work

* fixup

* add missing import

* fixup

* remove `result` property (it's not a function)

* Revert "remove `result` property (it's not a function)"

This reverts commit 57c8526.

* functions adjustments
only show parameters section if there are parameters
only show results if result is not `void` or user-specified

* move heading out of example children

* Update docs/shared/ApiDoc/EnumDetails.js

Co-authored-by: Jerel Miller <[email protected]>

* remove obsolete props

* address top padding for "smaller" headings

* review feedback

* fixup codeblock

* move `SourceLink` out of `Heading`

* throw an error if both `as` and `headingLevel` are specified in `Heading`

* move jsx

* always link headings

* move headings out of table components

* review comment

* Update docs/shared/ApiDoc/Tuple.js

Co-authored-by: Jerel Miller <[email protected]>

* nit :)

* more updates

* fix link

---------

Co-authored-by: Jerel Miller <[email protected]>
  • Loading branch information
@phryneas @jerelmiller
phryneas and jerelmiller authored Jan 24, 2024
1 parent 25b83da commit 2a67ffc
Show file tree
Hide file tree
Showing 67 changed files with 2,830 additions and 3,266 deletions.
2 changes: 1 addition & 1 deletion .api-reports/api-report-cache.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ export namespace DataProxy {
}
// (undocumented)
export interface ReadFragmentOptions<TData, TVariables> extends Fragment<TVariables, TData> {
// @deprecated (undocumented)
// @deprecated
canonizeResults?: boolean;
optimistic?: boolean;
returnPartialData?: boolean;
Expand Down
88 changes: 48 additions & 40 deletions .api-reports/api-report-core.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -253,14 +253,18 @@ export interface ApolloPayloadResult<TData = Record<string, any>, TExtensions =
}

// @public (undocumented)
export type ApolloQueryResult<T> = {
export interface ApolloQueryResult<T> {
// (undocumented)
data: T;
errors?: ReadonlyArray<GraphQLError>;
error?: ApolloError;
errors?: ReadonlyArray<GraphQLError>;
// (undocumented)
loading: boolean;
// (undocumented)
networkStatus: NetworkStatus;
// (undocumented)
partial?: boolean;
};
}

// @public (undocumented)
export type ApolloReducerConfig = {
Expand Down Expand Up @@ -479,7 +483,7 @@ export namespace DataProxy {
}
// (undocumented)
export interface ReadFragmentOptions<TData, TVariables> extends Fragment<TVariables, TData> {
// @deprecated (undocumented)
// @deprecated
canonizeResults?: boolean;
optimistic?: boolean;
returnPartialData?: boolean;
Expand Down Expand Up @@ -591,9 +595,7 @@ export type DocumentTransformCacheKey = ReadonlyArray<unknown>;

// @public (undocumented)
interface DocumentTransformOptions {
// (undocumented)
cache?: boolean;
// (undocumented)
getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined;
}

Expand Down Expand Up @@ -766,9 +768,7 @@ export interface FetchMoreOptions<TData = any, TVariables = OperationVariables>
export interface FetchMoreQueryOptions<TVariables, TData = any> {
// (undocumented)
context?: DefaultContext;
// (undocumented)
query?: DocumentNode | TypedDocumentNode<TData, TVariables>;
// (undocumented)
variables?: Partial<TVariables>;
}

Expand Down Expand Up @@ -1359,12 +1359,10 @@ interface MutationBaseOptions<TData = any, TVariables = OperationVariables, TCon
// @public (undocumented)
export type MutationFetchPolicy = Extract<FetchPolicy, "network-only" | "no-cache">;

// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts
// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts
//
// @public (undocumented)
export interface MutationOptions<TData = any, TVariables = OperationVariables, TContext = DefaultContext, TCache extends ApolloCache<any> = ApolloCache<any>> extends MutationBaseOptions<TData, TVariables, TContext, TCache> {
fetchPolicy?: MutationFetchPolicy;
keepRootFields?: boolean;
export interface MutationOptions<TData = any, TVariables = OperationVariables, TContext = DefaultContext, TCache extends ApolloCache<any> = ApolloCache<any>> extends MutationSharedOptions<TData, TVariables, TContext, TCache> {
mutation: DocumentNode | TypedDocumentNode<TData, TVariables>;
}

Expand All @@ -1382,6 +1380,14 @@ export type MutationQueryReducersMap<T = {
[queryName: string]: MutationQueryReducer<T>;
};

// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts
//
// @public (undocumented)
interface MutationSharedOptions<TData = any, TVariables = OperationVariables, TContext = DefaultContext, TCache extends ApolloCache<any> = ApolloCache<any>> extends MutationBaseOptions<TData, TVariables, TContext, TCache> {
fetchPolicy?: MutationFetchPolicy;
keepRootFields?: boolean;
}

// @public (undocumented)
interface MutationStoreValue {
// (undocumented)
Expand All @@ -1394,7 +1400,7 @@ interface MutationStoreValue {
variables: Record<string, any>;
}

// @public (undocumented)
// @public @deprecated (undocumented)
export type MutationUpdaterFn<T = {
[key: string]: any;
}> = (cache: ApolloCache<T>, mutationResult: FetchResult<T>) => void;
Expand Down Expand Up @@ -1486,7 +1492,6 @@ export class ObservableQuery<TData = any, TVariables extends OperationVariables
queryInfo: QueryInfo;
options: WatchQueryOptions<TVariables, TData>;
});
// (undocumented)
fetchMore<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & {
updateQuery?: (previousQueryResult: TData, options: {
fetchMoreResult: TFetchData;
Expand Down Expand Up @@ -1535,15 +1540,10 @@ export class ObservableQuery<TData = any, TVariables extends OperationVariables
setVariables(variables: TVariables): Promise<ApolloQueryResult<TData> | void>;
// (undocumented)
silentSetOptions(newOptions: Partial<WatchQueryOptions<TVariables, TData>>): void;
// (undocumented)
startPolling(pollInterval: number): void;
// (undocumented)
stopPolling(): void;
// (undocumented)
subscribeToMore<TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables>(options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData>): () => void;
// (undocumented)
updateQuery<TVars extends OperationVariables = TVariables>(mapFn: (previousQueryResult: TData, options: Pick<WatchQueryOptions<TVars, TData>, "variables">) => TData): void;
// (undocumented)
get variables(): TVariables | undefined;
}

Expand Down Expand Up @@ -1830,12 +1830,13 @@ class QueryManager<TStore> {

// @public
interface QueryOptions<TVariables = OperationVariables, TData = any> {
// @deprecated (undocumented)
// @deprecated
canonizeResults?: boolean;
context?: DefaultContext;
errorPolicy?: ErrorPolicy;
fetchPolicy?: FetchPolicy;
notifyOnNetworkStatusChange?: boolean;
// @deprecated
partialRefetch?: boolean;
pollInterval?: number;
query: DocumentNode | TypedDocumentNode<TData, TVariables>;
Expand Down Expand Up @@ -2012,6 +2013,26 @@ export type ServerParseError = Error & {

export { setLogVerbosity }

// @public (undocumented)
interface SharedWatchQueryOptions<TVariables extends OperationVariables, TData> {
// @deprecated
canonizeResults?: boolean;
context?: DefaultContext;
errorPolicy?: ErrorPolicy;
fetchPolicy?: WatchQueryFetchPolicy;
initialFetchPolicy?: WatchQueryFetchPolicy;
// Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts
nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy);
notifyOnNetworkStatusChange?: boolean;
// @deprecated
partialRefetch?: boolean;
pollInterval?: number;
refetchWritePolicy?: RefetchWritePolicy;
returnPartialData?: boolean;
skipPollAttempt?: () => boolean;
variables?: TVariables;
}

// @public (undocumented)
export interface SingleExecutionResult<TData = Record<string, any>, TContext = DefaultContext, TExtensions = Record<string, any>> extends ExecutionResult<TData, TExtensions> {
// (undocumented)
Expand Down Expand Up @@ -2156,24 +2177,11 @@ export interface UriFunction {
// @public (undocumented)
export type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network";

// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts
//
// @public
export interface WatchQueryOptions<TVariables extends OperationVariables = OperationVariables, TData = any> {
// @deprecated (undocumented)
canonizeResults?: boolean;
context?: DefaultContext;
errorPolicy?: ErrorPolicy;
fetchPolicy?: WatchQueryFetchPolicy;
initialFetchPolicy?: WatchQueryFetchPolicy;
// Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts
nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy);
notifyOnNetworkStatusChange?: boolean;
partialRefetch?: boolean;
pollInterval?: number;
export interface WatchQueryOptions<TVariables extends OperationVariables = OperationVariables, TData = any> extends SharedWatchQueryOptions<TVariables, TData> {
query: DocumentNode | TypedDocumentNode<TData, TVariables>;
refetchWritePolicy?: RefetchWritePolicy;
returnPartialData?: boolean;
skipPollAttempt?: () => boolean;
variables?: TVariables;
}

// @public (undocumented)
Expand Down Expand Up @@ -2214,13 +2222,13 @@ interface WriteContext extends ReadMergeModifyContext {
// src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts
// src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts
// src/cache/inmemory/types.ts:139:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts
// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts
// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts
// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts
// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts
// src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts
// src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts
// src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts
// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts
// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts
// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts
// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts
// src/link/http/selectHttpOptionsAndBody.ts:128:32 - (ae-forgotten-export) The symbol "HttpQueryOptions" needs to be exported by the entry point index.d.ts

// (No @packageDocumentation comment for this package)
Expand Down
Loading

0 comments on commit 2a67ffc

Please sign in to comment.