Skip to content

chore: Updated API reference comments to tsdoc.org standards #1242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 30, 2021
Merged

chore: Updated API reference comments to tsdoc.org standards #1242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8e74ff
chore: Updated API reference comments to tsdoc.org standards
hiranya911 Apr 27, 2021
0dfac02
chore: Removed more old jsdoc syntax
hiranya911 Apr 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion etc/firebase-admin.messaging.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,6 @@ export type Message = TokenMessage | TopicMessage | ConditionMessage;

// @public
export class Messaging {
constructor(app: App);
get app(): App;
send(message: Message, dryRun?: boolean): Promise<string>;
sendAll(messages: Message[], dryRun?: boolean): Promise<BatchResponse>;
Expand Down
28 changes: 11 additions & 17 deletions src/app/core.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,29 +20,30 @@ import { Agent } from 'http';
import { Credential } from './credential';

/**
* Available options to pass to [`initializeApp()`](admin#.initializeApp).
* Available options to pass to {@link firebase-admin.app#initializeApp}.
*/
export interface AppOptions {

/**
* A {@link Credential `Credential`} object used to
* authenticate the Admin SDK.
*
* See [Initialize the SDK](/docs/admin/setup#initialize_the_sdk) for detailed
* documentation and code samples.
* See {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
* for detailed documentation and code samples.
*/
credential?: Credential;

/**
* The object to use as the [`auth`](/docs/reference/security/database/#auth)
* The object to use as the {@link https://firebase.google.com/docs/reference/security/database/#auth | auth}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know if it's possible to keep the code styling?

Not required, but nice to have.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Haven't been able to get this to work. I've asked tsdoc.org community to see if I've missed something.

* variable in your Realtime Database Rules when the Admin SDK reads from or
* writes to the Realtime Database. This allows you to downscope the Admin SDK
* from its default full read and write privileges.
*
* You can pass `null` to act as an unauthenticated client.
*
* See
* [Authenticate with limited privileges](/docs/database/admin/start#authenticate-with-limited-privileges)
* {@link https://firebase.google.com/docs/database/admin/start#authenticate-with-limited-privileges |
* Authenticate with limited privileges}
* for detailed documentation and code samples.
*/
databaseAuthVariableOverride?: object | null;
Expand Down Expand Up @@ -71,7 +72,7 @@ export interface AppOptions {
projectId?: string;

/**
* An [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
* An {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
* to be used when making outgoing HTTP calls. This Agent instance is used
* by all services that make REST calls (e.g. `auth`, `messaging`,
* `projectManagement`).
Expand All @@ -87,12 +88,6 @@ export interface AppOptions {
/**
* A Firebase app holds the initialization information for a collection of
* services.
*
* Do not call this constructor directly. Instead, use
* {@link
* https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
* `admin.initializeApp()`}
* to create an app.
*/
export interface App {

Expand All @@ -119,10 +114,7 @@ export interface App {

/**
* The (read-only) configuration options for this app. These are the original
* parameters given in
* {@link
* https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
* `admin.initializeApp()`}.
* parameters given in {@link firebase-admin.app#initializeApp}.
*
* @example
* ```javascript
Expand Down Expand Up @@ -170,7 +162,9 @@ export interface FirebaseError {
stack?: string;

/**
* @return A JSON-serializable representation of this object.
* Returns a JSON-serializable object representation of this error.
*
* @returns A JSON-serializable representation of this object.
*/
toJSON(): object;
}
Expand Down
44 changes: 14 additions & 30 deletions src/app/credential-factory.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,22 +28,16 @@ const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {};

/**
* Returns a credential created from the
* {@link
* https://developers.google.com/identity/protocols/application-default-credentials
* Google Application Default Credentials}
* {@link https://developers.google.com/identity/protocols/application-default-credentials |
* Google Application Default Credentials}
* that grants admin access to Firebase services. This credential can be used
* in the call to
* {@link
* https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
* `admin.initializeApp()`}.
* in the call to {@link firebase-admin.app#initializeApp}.
*
* Google Application Default Credentials are available on any Google
* infrastructure, such as Google App Engine and Google Compute Engine.
*
* See
* {@link
* https://firebase.google.com/docs/admin/setup#initialize_the_sdk
* Initialize the SDK}
* {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
* for more details.
*
* @example
Expand All @@ -54,10 +48,10 @@ const globalRefreshTokenCreds: { [key: string]: RefreshTokenCredential } = {};
* });
* ```
*
* @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
* @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
* to be used when retrieving access tokens from Google token servers.
*
* @return A credential authenticated via Google
* @returns A credential authenticated via Google
* Application Default Credentials that can be used to initialize an app.
*/
export function applicationDefault(httpAgent?: Agent): Credential {
Expand All @@ -70,15 +64,10 @@ export function applicationDefault(httpAgent?: Agent): Credential {
/**
* Returns a credential created from the provided service account that grants
* admin access to Firebase services. This credential can be used in the call
* to
* {@link
* https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
* `admin.initializeApp()`}.
* to {@link firebase-admin.app#initializeApp}.
*
* See
* {@link
* https://firebase.google.com/docs/admin/setup#initialize_the_sdk
* Initialize the SDK}
* {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
* for more details.
*
* @example
Expand Down Expand Up @@ -106,10 +95,10 @@ export function applicationDefault(httpAgent?: Agent): Credential {
*
* @param serviceAccountPathOrObject The path to a service
* account key JSON file or an object representing a service account key.
* @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
* @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
* to be used when retrieving access tokens from Google token servers.
*
* @return A credential authenticated via the
* @returns A credential authenticated via the
* provided service account that can be used to initialize an app.
*/
export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAgent?: Agent): Credential {
Expand All @@ -124,15 +113,10 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg
/**
* Returns a credential created from the provided refresh token that grants
* admin access to Firebase services. This credential can be used in the call
* to
* {@link
* https://firebase.google.com/docs/reference/admin/node/admin#.initializeApp
* `admin.initializeApp()`}.
* to {@link firebase-admin.app#initializeApp}.
*
* See
* {@link
* https://firebase.google.com/docs/admin/setup#initialize_the_sdk
* Initialize the SDK}
* {@link https://firebase.google.com/docs/admin/setup#initialize_the_sdk | Initialize the SDK}
* for more details.
*
* @example
Expand All @@ -148,10 +132,10 @@ export function cert(serviceAccountPathOrObject: string | ServiceAccount, httpAg
* @param refreshTokenPathOrObject The path to a Google
* OAuth2 refresh token JSON file or an object representing a Google OAuth2
* refresh token.
* @param httpAgent Optional [HTTP Agent](https://nodejs.org/api/http.html#http_class_http_agent)
* @param httpAgent Optional {@link https://nodejs.org/api/http.html#http_class_http_agent | HTTP Agent}
* to be used when retrieving access tokens from Google token servers.
*
* @return A credential authenticated via the
* @returns A credential authenticated via the
* provided service account that can be used to initialize an app.
*/
export function refreshToken(refreshTokenPathOrObject: string | object, httpAgent?: Agent): Credential {
Expand Down
7 changes: 1 addition & 6 deletions src/app/credential.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,7 @@ export interface Credential {
* Returns a Google OAuth2 access token object used to authenticate with
* Firebase services.
*
* This object contains the following properties:
* * `access_token` (`string`): The actual Google OAuth2 access token.
* * `expires_in` (`number`): The number of seconds from when the token was
* issued that it expires.
*
* @return A Google OAuth2 access token object.
* @returns A Google OAuth2 access token object.
*/
getAccessToken(): Promise<GoogleOAuthAccessToken>;
}
24 changes: 12 additions & 12 deletions src/app/firebase-app.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the Auth service instance associated with this app.
*
* @return The Auth service instance of this app.
* @returns The Auth service instance of this app.
*/
public auth(): Auth {
const fn = require('../auth/index').getAuth;
Expand All @@ -202,7 +202,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the Database service for the specified URL, and the current app.
*
* @return The Database service instance of this app.
* @returns The Database service instance of this app.
*/
public database(url?: string): Database {
const fn = require('../database/index').getDatabaseWithUrl;
Expand All @@ -212,7 +212,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the Messaging service instance associated with this app.
*
* @return The Messaging service instance of this app.
* @returns The Messaging service instance of this app.
*/
public messaging(): Messaging {
const fn = require('../messaging/index').getMessaging;
Expand All @@ -222,7 +222,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the Storage service instance associated with this app.
*
* @return The Storage service instance of this app.
* @returns The Storage service instance of this app.
*/
public storage(): Storage {
const fn = require('../storage/index').getStorage;
Expand All @@ -237,7 +237,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the InstanceId service instance associated with this app.
*
* @return The InstanceId service instance of this app.
* @returns The InstanceId service instance of this app.
*/
public instanceId(): InstanceId {
const fn = require('../instance-id/index').getInstanceId;
Expand All @@ -247,7 +247,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the MachineLearning service instance associated with this app.
*
* @return The Machine Learning service instance of this app
* @returns The Machine Learning service instance of this app
*/
public machineLearning(): MachineLearning {
const fn = require('../machine-learning/index').getMachineLearning;
Expand All @@ -257,7 +257,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the ProjectManagement service instance associated with this app.
*
* @return The ProjectManagement service instance of this app.
* @returns The ProjectManagement service instance of this app.
*/
public projectManagement(): ProjectManagement {
const fn = require('../project-management/index').getProjectManagement;
Expand All @@ -267,7 +267,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the SecurityRules service instance associated with this app.
*
* @return The SecurityRules service instance of this app.
* @returns The SecurityRules service instance of this app.
*/
public securityRules(): SecurityRules {
const fn = require('../security-rules/index').getSecurityRules;
Expand All @@ -277,7 +277,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the RemoteConfig service instance associated with this app.
*
* @return The RemoteConfig service instance of this app.
* @returns The RemoteConfig service instance of this app.
*/
public remoteConfig(): RemoteConfig {
const fn = require('../remote-config/index').getRemoteConfig;
Expand All @@ -287,7 +287,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the name of the FirebaseApp instance.
*
* @return The name of the FirebaseApp instance.
* @returns The name of the FirebaseApp instance.
*/
get name(): string {
this.checkDestroyed_();
Expand All @@ -297,7 +297,7 @@ export class FirebaseApp implements app.App {
/**
* Returns the options for the FirebaseApp instance.
*
* @return The options for the FirebaseApp instance.
* @returns The options for the FirebaseApp instance.
*/
get options(): AppOptions {
this.checkDestroyed_();
Expand All @@ -314,7 +314,7 @@ export class FirebaseApp implements app.App {
/**
* Deletes the FirebaseApp instance.
*
* @return An empty Promise fulfilled once the FirebaseApp instance is deleted.
* @returns An empty Promise fulfilled once the FirebaseApp instance is deleted.
*/
public delete(): Promise<void> {
this.checkDestroyed_();
Expand Down
8 changes: 4 additions & 4 deletions src/app/firebase-namespace.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ export class FirebaseNamespaceInternals {
* to a file.
* @param appName Optional name of the FirebaseApp instance.
*
* @return A new App instance.
* @returns A new App instance.
*/
public initializeApp(options?: AppOptions, appName = DEFAULT_APP_NAME): App {
if (typeof options === 'undefined') {
Expand Down Expand Up @@ -114,7 +114,7 @@ export class FirebaseNamespaceInternals {
* if no name is provided).
*
* @param appName Optional name of the FirebaseApp instance to return.
* @return The App instance which has the provided name.
* @returns The App instance which has the provided name.
*/
public app(appName = DEFAULT_APP_NAME): App {
if (typeof appName !== 'string' || appName === '') {
Expand Down Expand Up @@ -360,7 +360,7 @@ export class FirebaseNamespace {
* otherwise it will be assumed to be pointing to a file.
* @param appName Optional name of the FirebaseApp instance.
*
* @return A new FirebaseApp instance.
* @returns A new FirebaseApp instance.
*/
public initializeApp(options?: AppOptions, appName?: string): App {
return this.INTERNAL.initializeApp(options, appName);
Expand All @@ -371,7 +371,7 @@ export class FirebaseNamespace {
* if no name is provided).
*
* @param appName Optional name of the FirebaseApp instance to return.
* @return The FirebaseApp instance which has the provided name.
* @returns The FirebaseApp instance which has the provided name.
*/
public app(appName?: string): App {
return this.INTERNAL.app(appName);
Expand Down
2 changes: 1 addition & 1 deletion src/auth/action-code-settings-builder.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,7 @@ export class ActionCodeSettingsBuilder {
* Returns the corresponding constructed server request corresponding to the
* current ActionCodeSettings.
*
* @return {EmailActionCodeRequest} The constructed EmailActionCodeRequest request.
* @returns The constructed EmailActionCodeRequest request.
*/
public buildRequest(): EmailActionCodeRequest {
const request: { [key: string]: any } = {
Expand Down
Loading