📖 Bento: Adopt new formatting for amp-base-carousel documentation

[caroqliu]

Related to #28284, incorporating format changes from #31944

[CrystalOnScript]

This looks amazing!!! I was mistaken about executable code samples and Bento, so just one comment about updating the code sample and a qq about one of the actions. Otherwise LGTM!

[CrystalOnScript]

Do they need to include index: in the argument? Or just the index number?

[caroqliu]

Just the index. The index: number is to give the parameter a type, but let me specify this inline instead so it's less confusing, something like this:

Suggested change

	**goToSlide(index: number)**
	Moves the carousel to the slide specified by the `index` argument.
	```
	api.goToSlide(0); // Advance to first slide.
	api.goToSlide(length - 1); // Advance to last slide.
	```
	**goToSlide(index)**
	Args:
	- `index`: number [required]
	Moves the carousel to the slide specified by the `index` argument.
	Note: `index` will be normalized to a number greater than or equal to `0` and less than the number of slides given.
	\```
	api.goToSlide(0); // Advance to first slide.
	api.goToSlide(length - 1); // Advance to last slide.
	\```

[dvoytenko]

TypeScript-like notation here I think is the best in the long term. We are also likely to publish TypeScript type declarations (based on our x.type.js) in the future too.

[caroqliu]

@dvoytenko are you suggesting keep as is?

[dvoytenko]

TypeScript-like notation here I think is the best in the long term. We are also likely to publish TypeScript type declarations (based on our x.type.js) in the future too.

[dvoytenko]

Hmm. I think we should continue advising to use CSS for this. E.g.

<style>
  #carousel1 {
    height: calc(100% * 3 * 3 / 2);
  }
  @media (min-width: 600px) {
    #carousel1 {
      height: calc(100% * 4 * 3 / 2);
    }
  }
</style>

Of course, that'd split the media queries between the element and the attributes. But IMHO it's better to fix one part of it than both have two parts "broken". We can also communicate later that we are pursuing Web spec update to support attribute media queries as well.

[caroqliu]

To clarify, this section is moved verbatim from its former location in the file, and the code samples here were created with the intention of being used on valid AMP documents. Do you still recommend making the change? Or perhaps duplicating the section so there is one version for valid AMP documents (status quo) and one version with the suggested CSS for Bento documents?

[dvoytenko]

If it's for valid AMP, then let's keep as is. Sorry for the confusion. But I think we'll be stumbling into these deltas for some time.