diff --git a/src/ui/Sort/Sort.ts b/src/ui/Sort/Sort.ts index 8b9e02ee07..077853a17c 100644 --- a/src/ui/Sort/Sort.ts +++ b/src/ui/Sort/Sort.ts @@ -18,29 +18,32 @@ export interface ISortOptions { caption?: string; } /** - * This component displays a sort criterion for searching. + * The Sort component renders a widget that the end user can interact with to sort query results according to a single + * criterion or list of criteria. */ export class Sort extends Component { static ID = 'Sort'; + /** * Options for the component * @componentOptions */ static options: ISortOptions = { + /** - * The criterion for sorting + * Specifies the criterion (or criteria) for sorting. * - * The available criteria are: + * The possible criteria are: * - `relevancy` - * - `Date` + * - `date` * - `qre` - * - `@fieldname` (replace fieldname with an actual field name (e.g. @syssize) + * - `@fieldname` (replace `fieldname` with an actual field name (e.g., `@syssize`) * - * A direction (ascending or descending) can be specified, for example "date ascending". + * You can also specify a direction (ascending or descending), for example `date ascending`. * - * A Sort component can have multiple criteria, passed as a list. + * You can pass an array containing multiple criteria to a Sort component. * - * This option is required. + * It is necessary to specify a value for this option in order for this component to work. */ sortCriteria: ComponentOptions.buildCustomListOption((values: string[] | SortCriteria[]) => { return _.map(values, (criteria) => { // 'any' because Underscore won't accept the union type as an argument. @@ -51,10 +54,11 @@ export class Sort extends Component { } }); }, { required: true }), + /** - * The caption to display on the element. + * Specifies the caption to display on the element. * - * If not specified, the component will use the tag body. + * If not specified, the component will use the tag body of the element. */ caption: ComponentOptions.buildLocalizedStringOption({ required: true }) }; @@ -62,10 +66,11 @@ export class Sort extends Component { private currentCriteria: SortCriteria; /** - * Create a new Sort component. - * @param element - * @param options - * @param bindings + * Creates a new Sort component. + * @param element The HTMLElement on which to instantiate the component. + * @param options The options for the Sort component. + * @param bindings The bindings that the component requires to function normally. If not set, these will be + * automatically resolved (with a slower execution time). */ constructor(public element: HTMLElement, public options?: ISortOptions, bindings?: IComponentBindings) { super(element, Sort.ID, bindings); @@ -95,10 +100,9 @@ export class Sort extends Component { } /** - * Select the Sort component. - * @param direction The sort direction (e.g. ascending, descending). - * - * Will trigger a query if the selection made the criteria change (if it was toggled). + * Selects the Sort component. Triggers a new query if selecting the component changes the current + * {@link Sort.options.sortCriteria} (if it is toggled). + * @param direction The sort direction. Can be either `ascending` or `descending`. */ public select(direction?: string) { if (direction) { @@ -128,15 +132,16 @@ export class Sort extends Component { } /** - * Get the current SortCriteria. + * Gets the current {@link Sort.options.sortCriteria}. + * @returns {SortCriteria} */ public getCurrentCriteria(): SortCriteria { return this.currentCriteria; } /** - * Returns true if one of the sort criterias matches the passed argument. - * @param sortId The sort criteria to verify with (e.g. 'date descending') + * Indicates whether the name of any of the {@link Sort.options.sortCriteria} matches the argument. + * @param sortId The sort criteria name to look for (e.g., `date descending`). */ public match(sortId: string) { return _.any(this.options.sortCriteria, (sortCriteria: SortCriteria) => sortId == sortCriteria.toString());