From a6edd119d0ed1d3c38c5d08cc10bdde70e2db8c0 Mon Sep 17 00:00:00 2001 From: atanasovg Date: Wed, 21 May 2014 15:15:48 +0300 Subject: [PATCH] Updated some APIs with @param defintions. Added .impl suffix to the ImageSource module. --- BCL.csproj | 2 +- Tests/image-source-tests.ts | 2 +- application/application.d.ts | 30 +++---- camera/camera.d.ts | 2 +- camera/camera.ios.ts | 5 +- console/console.d.ts | 14 ++++ file-system/file-system.d.ts | 80 +++++++++++-------- http/http-common.ts | 2 +- http/http.d.ts | 2 +- image-source/image-source.d.ts | 36 ++++++--- .../{image-source.ts => image-source.impl.ts} | 5 +- location/location.impl.ts | 2 +- 12 files changed, 112 insertions(+), 70 deletions(-) rename image-source/{image-source.ts => image-source.impl.ts} (92%) diff --git a/BCL.csproj b/BCL.csproj index f2a36aea9..c6bc42f54 100644 --- a/BCL.csproj +++ b/BCL.csproj @@ -130,7 +130,7 @@ - + image-source.d.ts diff --git a/Tests/image-source-tests.ts b/Tests/image-source-tests.ts index 2acb5494d..afc5d080c 100644 --- a/Tests/image-source-tests.ts +++ b/Tests/image-source-tests.ts @@ -12,7 +12,7 @@ // ## Loading and saving images // -import imageSource = require("image-source/image-source"); +import imageSource = require("image-source"); import fs = require("file-system"); import app = require("application"); import TKUnit = require("Tests/TKUnit"); diff --git a/application/application.d.ts b/application/application.d.ts index 84b1fb96a..b8dee2a63 100644 --- a/application/application.d.ts +++ b/application/application.d.ts @@ -5,46 +5,52 @@ declare module "application" { * The main entry point event. This method is expected to return an instance of the root UI for the application. * This will be an Activity extends for Android and a RootViewController for iOS. */ - function onLaunch(): any; + export function onLaunch(): any; /** * This method will be called when the Application is suspended. */ - function onSuspend(); + export function onSuspend(); /** * This method will be called when the Application is resumed after it has been suspended. */ - function onResume(); + export function onResume(); /** * This method will be called when the Application is about to exit. */ - function onExit(); + export function onExit(); /** * This method will be called when there is low memory on the target device. */ - function onLowMemory(); + export function onLowMemory(); /** * This is the Android-specific application object instance. * Encapsulates methods and properties specific to the Android platform. * Will be undefined when TargetOS is iOS. */ - var android: AndroidApplication; + export var android: AndroidApplication; /** * This is the iOS-specific application object instance. * Encapsulates methods and properties specific to the iOS platform. * Will be undefined when TargetOS is Android. */ - var ios: iOSApplication; + export var ios: iOSApplication; + + /** + * Entry point for the module. Initializes the Application singleton and hooks application lifecycle events. + * @param nativeApp The instance of the platform Application object - e.g. android.app.Application + */ + export function init(nativeApp: any); /** * The abstraction of an Android-specific application object. */ - class AndroidApplication { + export class AndroidApplication { /** * The android.app.Application object instance provided to the init of the module. */ @@ -73,6 +79,7 @@ declare module "application" { /** * This method is called by the JavaScript Bridge when navigation to a new activity is triggered. * The return value of this method should be com.tns.NativeScriptActivity.extends implementation. + * @param intent The android.content.Intent object for which the activity is required. */ public getActivity: (intent: android.content.Intent) => any; @@ -115,7 +122,7 @@ declare module "application" { /** * The abstraction of an iOS-specific application object. */ - class iOSApplication { + export class iOSApplication { /** * The root view controller for the application. */ @@ -126,9 +133,4 @@ declare module "application" { */ public nativeApp: UIKit.UIApplication; } - - /** - * Entry point for the module. Initializes the Application singleton and hooks application lifecycle events. - */ - function init(nativeApp: any); } \ No newline at end of file diff --git a/camera/camera.d.ts b/camera/camera.d.ts index 6912356eb..81595ba54 100644 --- a/camera/camera.d.ts +++ b/camera/camera.d.ts @@ -2,7 +2,7 @@ declare module "camera" { import promises = require("promises/promises"); - import imageSource = require("image-source/image-source"); + import imageSource = require("image-source"); enum CameraPosition { FRONT = 0, diff --git a/camera/camera.ios.ts b/camera/camera.ios.ts index 635063a86..b2756eb72 100644 --- a/camera/camera.ios.ts +++ b/camera/camera.ios.ts @@ -1,6 +1,5 @@ - -import promises = require("promises/promises"); -import imageSource = require("image-source/image-source"); +import promises = require("promises/promises"); +import imageSource = require("image-source"); import types = require("camera/camera-types"); var imagePickerController; diff --git a/console/console.d.ts b/console/console.d.ts index bcf74972c..edc1a820d 100644 --- a/console/console.d.ts +++ b/console/console.d.ts @@ -5,36 +5,49 @@ export declare class Console { /** * Begins counting a time span for a given name (key). + * @param reportName The key for the operation. */ public time(reportName: string): void; /** * Ends a previously started time span through the time method. + * @param reportName The key for the operation. Must have an already started time(reportName) operation with the same key. */ public timeEnd(reportName: string): void; /** * Asserts a boolean condition and prints a message in case the assert fails. + * @param test A value that should not be Falsy. + * @param message The message to be displayed in case the asserted value is Falsy. + * @param formatParams Optional formatting parameters to be applied to the printed message. */ public assert(test: boolean, message: string, ...formatParams: any[]): void; /** * Reports some information. + * @param message The information message to be printed to the console. + * @param formatParams Optional formatting parameters to be applied to the printed message. */ public info(message: any, ...formatParams: any[]): void; /** * Reports a warning. + * @param message The warning message to be printed to the console. + * @param formatParams Optional formatting parameters to be applied to the printed message. */ public warn(message: any, ...formatParams: any[]): void; /** * Reports an error. + * @param message The error message to be printed to the console. + * @param formatParams Optional formatting parameters to be applied to the printed message. */ public error(message: any, ...formatParams: any[]): void; /** * Verbously logs a message. + * @param message The message to be printed to the console. + * @param formatParams Optional formatting parameters to be applied to the printed message. */ public log(message: any, ...formatParams: any[]): void; @@ -45,6 +58,7 @@ export declare class Console { /** * Prints the state of the specified object to the console. + * @param obj The object instance to be dumped. */ public dump(obj: any): void; } \ No newline at end of file diff --git a/file-system/file-system.d.ts b/file-system/file-system.d.ts index 8f554773a..53fa3ed6d 100644 --- a/file-system/file-system.d.ts +++ b/file-system/file-system.d.ts @@ -3,7 +3,7 @@ declare module "file-system" { import promises = require("promises/promises"); - class FileSystemEntity { + export class FileSystemEntity { /** * Gets the Date object specifying the last time this entity was modified. */ @@ -33,62 +33,71 @@ declare module "file-system" { /** * Renames the current entity using the specified name. + * @param newName The new name to be applied to the entity. */ public rename(newName: string): promises.Promise; } - class File extends FileSystemEntity { + export class File extends FileSystemEntity { /** - * Checks whether a File with the specified path already exists. - */ + * Checks whether a File with the specified path already exists. + * @param path The path to check for. + */ public static exists(path: string): boolean; /** - * Gets the extension of the file. - */ + * Gets the extension of the file. + */ public extension: string; /** - * Gets a value indicating whether the file is currently locked, meaning a background operation associated with this file is running. - */ + * Gets a value indicating whether the file is currently locked, meaning a background operation associated with this file is running. + */ public isLocked: boolean; /** - * Gets or creates a File entity at the specified path. - */ + * Gets or creates a File entity at the specified path. + * @param path The path to get/create the file at. + */ public static fromPath(path: string): File; /** - * Reads the content of the file as a string using the specified encoding (defaults to UTF-8). - */ + * Reads the content of the file as a string using the specified encoding (defaults to UTF-8). + * @param encoding An optional value specifying the preferred encoding (defaults to UTF-8). + */ public readText(encoding?: string): promises.Promise; /** - * Writes the provided string to the file, using the specified encoding (defaults to UTF-8). - */ + * Writes the provided string to the file, using the specified encoding (defaults to UTF-8). + * @param content The content to be saved to the file. + * @param encoding An optional value specifying the preferred encoding (defaults to UTF-8). + */ public writeText(content: string, encoding?: string): promises.Promise; } - class Folder extends FileSystemEntity { + export class Folder extends FileSystemEntity { /** - * Determines whether this instance is a KnownFolder (accessed through the KnownFolders object). - */ + * Determines whether this instance is a KnownFolder (accessed through the KnownFolders object). + */ public isKnown: boolean; /** - * Gets or creates a Folder entity at the specified path. - */ + * Gets or creates a Folder entity at the specified path. + * @param path The path to get/create the folder at. + */ public static fromPath(path: string): Folder; /** - * Checks whether a Folder with the specified path already exists. - */ + * Checks whether a Folder with the specified path already exists. + * @param path The path to check for. + */ public static exists(path: string): boolean; /** - Checks whether this Folder contains an Entity with the specified name. - The path of the folder is added to the name to resolve the complete path to check for. - */ + * Checks whether this Folder contains an Entity with the specified name. + * The path of the folder is added to the name to resolve the complete path to check for. + * @param name The name of the entity to check for. + */ public contains(name: string): boolean; /** @@ -97,12 +106,14 @@ declare module "file-system" { public clear(): promises.Promise; /** - * Gets or creates a File entity with the specified name within this Folder. - */ + * Gets or creates a File entity with the specified name within this Folder. + * @param name The name of the file to get/create. + */ public getFile(name: string): File; /** * Gets or creates a Folder entity with the specified name within this Folder. + * @param name The name of the folder to get/create. */ public getFolder(name: string): Folder; @@ -112,17 +123,16 @@ declare module "file-system" { public getEntities(): promises.Promise>; /** - Enumerates all the top-level FileSystem entities residing within this folder. - The first parameter is a callback that receives the current entity. - If the callback returns false this will mean for the iteration to stop. + * Enumerates all the top-level FileSystem entities residing within this folder. + * @param onEntity A callback that receives the current entity. If the callback returns false this will mean for the iteration to stop. */ public eachEntity(onEntity: (entity: FileSystemEntity) => boolean); } /** - * Provides access to the top-level Folders instances that are accessible from the application. Use these as entry points to access the FileSystem. - */ - module knownFolders { + * Provides access to the top-level Folders instances that are accessible from the application. Use these as entry points to access the FileSystem. + */ + export module knownFolders { /** * Gets the Documents folder available for the current application. This Folder is private for the application and not accessible from Users/External apps. */ @@ -137,14 +147,16 @@ declare module "file-system" { /** * Enables path-specific operations like join, extension, etc. */ - module path { + export module path { /** - * Normalizes a path, taking care of occurrances like ".." and "//" + * Normalizes a path, taking care of occurrances like ".." and "//". + * @param path The path to be normalized. */ export function normalize(path: string): string; /** * Joins all the provided string components, forming a valid and normalized path. + * @param paths An array of string components to be joined. */ export function join(...paths: string[]): string; diff --git a/http/http-common.ts b/http/http-common.ts index 09142a7cf..146e8a206 100644 --- a/http/http-common.ts +++ b/http/http-common.ts @@ -1,4 +1,4 @@ -import image = require("image-source/image-source"); +import image = require("image-source"); import promises = require("promises/promises"); import http = require("http"); diff --git a/http/http.d.ts b/http/http.d.ts index cb89b7c09..6d4367b2a 100644 --- a/http/http.d.ts +++ b/http/http.d.ts @@ -1,6 +1,6 @@  declare module "http" { - import image = require("image-source/image-source"); + import image = require("image-source"); import promises = require("promises/promises"); function getString(url: string): promises.Promise diff --git a/image-source/image-source.d.ts b/image-source/image-source.d.ts index 19501c4e6..b08515e05 100644 --- a/image-source/image-source.d.ts +++ b/image-source/image-source.d.ts @@ -5,7 +5,7 @@ declare module "image-source" { /** * Defines the recognized image formats. */ - enum ImageFormat { + export enum ImageFormat { PNG, JPEG, } @@ -13,7 +13,7 @@ declare module "image-source" { /** * Encapsulates the common abstraction behind a platform specific object (typically a Bitmap) that is used as a source for images. */ - class ImageSource { + export class ImageSource { /** * Gets the height of this instance. This is a read-only property. */ @@ -36,54 +36,66 @@ declare module "image-source" { /** * Loads this instance from the specified resource name. + * @param name The name of the resource (without its extension). */ loadFromResource(name: string): boolean; /** * Loads this instance from the specified file. + * @param path The location of the file on the file system. */ loadFromFile(path: string): boolean; /** * Loads this instance from the specified native image data. + * @param data The native data (byte array) to load the image from. This will be either Stream for Android or NSData for iOS. */ loadFromData(data: any): boolean; /** * Sets the provided native source object (typically a Bitmap). * This will update either the android or ios properties, depending on the target os. + * @param source The native image object. Will be either a Bitmap for Android or a UIImage for iOS. */ setNativeSource(source: any): boolean; /** * Saves this instance to the specified file, using the provided image format and quality. + * @param path The path of the file on the file system to save to. + * @param format The format (encoding) of the image. + * @param quality Optional parameter, specifying the quality of the encoding. Defaults to the maximum available quality. */ saveToFile(path: string, format: ImageFormat, quality?: number): boolean; } /** - * Creates a new Image instance and loads it from the specified resource name. + * Creates a new ImageSource instance and loads it from the specified resource name. + * @param name The name of the resource (without its extension). */ - function fromResource(name: string): ImageSource; + export function fromResource(name: string): ImageSource; /** - * Creates a new Image instance and loads it from the specified file. + * Creates a new ImageSource instance and loads it from the specified file. + * @param path The location of the file on the file system. */ - function fromFile(path: string): ImageSource; + export function fromFile(path: string): ImageSource; /** - * Creates a new Image instance and loads it from the specified resource name. + * Creates a new ImageSource instance and loads it from the specified resource name. + * @param data The native data (byte array) to load the image from. This will be either Stream for Android or NSData for iOS. */ - function fromData(data: any): ImageSource; + export function fromData(data: any): ImageSource; /** - * Creates a new Image instance and sets the provided native source object (typically a Bitmap). + * Creates a new ImageSource instance and sets the provided native source object (typically a Bitmap). * The native source object will update either the android or ios properties, depending on the target os. + * @param source The native image object. Will be either a Bitmap for Android or a UIImage for iOS. */ - function fromNativeSource(source: any): ImageSource; + export function fromNativeSource(source: any): ImageSource; /** - * Downloads the image from the provided Url and creates a new Image instance from it. + * Downloads the image from the provided Url and creates a new ImageSource instance from it. + * @param url The link to the remote image object. This operation will download and decode the image. */ - function fromUrl(url: string): promises.Promise; + export function fromUrl(url: string): promises.Promise; } \ No newline at end of file diff --git a/image-source/image-source.ts b/image-source/image-source.impl.ts similarity index 92% rename from image-source/image-source.ts rename to image-source/image-source.impl.ts index 5643ef620..bf679c4e4 100644 --- a/image-source/image-source.ts +++ b/image-source/image-source.impl.ts @@ -3,6 +3,9 @@ import native = require("image-source/image-source-native"); import promises = require("promises/promises"); import http = require("http"); +// This is used for definition purposes only, it does not generate JavaScript for it. +import definition = require("image-source"); + export enum ImageFormat { PNG, JPEG, @@ -105,6 +108,6 @@ export function fromNativeSource(source: any): ImageSource { return image.setNativeSource(source) ? image : null; } -export function fromUrl(url: string): promises.Promise { +export function fromUrl(url: string): promises.Promise { return http.getImage(url); } \ No newline at end of file diff --git a/location/location.impl.ts b/location/location.impl.ts index efd864a24..8b8c5d5ef 100644 --- a/location/location.impl.ts +++ b/location/location.impl.ts @@ -2,7 +2,7 @@ import promises = require("promises/promises"); import timer = require("timer/timer"); import types = require("location/location-types"); -import locationManagerModule = require("location"); +import locationManagerModule = require("location/location-manager"); // merge the exports of the types module with the exports of this file declare var exports;