docs(snackbar): Add description for MatSnackBarHorizontalPosition and MatSnackBarVerticalPosition

[julianobrasil]

Bug, feature request, or proposal:

Request: apparently the docs generator doesn't take code comments associated with types definitions and interfaces to the docs site. So there should be some topic on the overview tab describing the possible values for MatSnackBarHorizontalPosition and MatSnackBarVerticalPosition.

What is the expected behavior?

Find explanation about the possible values for MatSnackBarHorizontalPosition and MatSnackBarVerticalPosition in the docs site.

What is the current behavior?

You must read the source code or rely on IDE features to know the possible values.

https://github.com/angular/material2/blob/c28549d088c4462bf64078db5442a123542bf1be/src/lib/snack-bar/snack-bar-config.ts#L16-L20

Generally speaking the automatic document generation should include types and interfaces documentation comments in the API tab.

[atinybeardedman]

I think this issue is more prevalent in the docs than just this one case. I see it is also present for the menu positioning (MenuPositionX/Y), but as a workaround there is an example of the possible values in the overview.

I might be missing something, but it seems like the generated api docs never show the possible values for these types that are only defined within class files. They only show values for Input properties of the main class in the file. For instance if I look at the MatFormField API docs, the possible values for MatHint's align Input are shown. But for the MatSnackBarHorizontalPosition in the case of the snackbar, that possible values aren't exposed.

I assume there's a reasoning behind the design choice but is there any reason we need an explicit type for MatSnackBarHorizontalPosition? Couldn't we just define the possible values like so:

horizontalPosition?: 'start' | 'center' | 'end' | 'left' | 'right' = 'center';

Edit: I realized the reason the values were shown for MatHint had to do with the fact that there are just the string values not a typed value and that's why. Has nothing to do with it being an Input property.

[julianobrasil]

I assume there's a reasoning behind the design choice but is there any reason we need an explicit type for MatSnackBarHorizontalPosition

Personally, I like the use of type. IMO, if you have multiple declarations of variables with the same restrictions across the files in the project, it will avoid typos and forgotten parts of your type. Even when you are apparently using that restrictions just once, in the future, the scenario can change.

[atinybeardedman]

That's a fair point. I did look and see that it was only being used in this file and that's why I raised it as a question. So then the docs just need to support showing these types that aren't part of the exported class of that file but used by it.

[julianobrasil]

Actually it would be nice to have associated classes with static attributes exposing the options inside the code, like:

/** Possible values for horizontalPosition on MatSnackBarConfig. */ 
export type MatSnackBarHorizontalPosition = 'start' | 'center' | 'end' | 'left' | 'right'; 

export class MatSnackBarHorizontalPositionOptions {
  static readonly START: MatSnackBarHorizontalPosition = 'start';
  static readonly CENTER: MatSnackBarHorizontalPosition = 'center';
  static readonly END: MatSnackBarHorizontalPosition = 'end';
  static readonly LEFT: MatSnackBarHorizontalPosition = 'left';
  static readonly RIGHT: MatSnackBarHorizontalPosition = 'right';
}

I'm not sure about how it would affect the final bundle size (not sure what kind of javascript this would generate).

[edited]: according to http://www.typescriptlang.org/play/, this does not generate much more javascript code than what is written in typescript.

[angular-automatic-lock-bot]

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}