Support for Device Frames

[ethankusters]

@ronnqvist

I think this is the core of our difference of opinion. In my mental model the device frame isn't a configuration of an image, it's a distinct element that contains an image.

I think this is the strongest argument and the question we need to answer here. Is a DeviceFrame a distinct element or is it a piece of configuration that Image and Video both happen to support?

To me it seems clear that the DeviceFrame as @dhristov pitched it is a piece of configuration because it doesn't support arbitrary content. An Image can add a device frame and a Video can add a device frame. This stands in direct contrast to something like the @Row/@Column directives which are distinct elements that hold arbitrary content.

Writing:

@DeviceFrame {
   @Image()
}

invites an obvious connection to

@Row {
   @Column {
       @Image
   }
}

which we actually don't want the user to connect. These are very different pieces of syntax that behave in a very different way.

What is the argument for DeviceFrame being it's own distinct element?

---

I agree with the limitations of the pitched syntax as you've described them – for example, if we want to add further configuration to image device frames in the future, we could end up with a confusing number of parameters on the @Image directive. But I think it's worse to break the current precedent we have of what a container directive is in a DocC article. Today, in DocC articles (this isn't true in Tutorials and is part of what makes Tutorial syntax difficult to learn) with they key exception of @Metadata and @Options (discussed here) a container directive can contain any kind of markup. We discussed the importance of this in the pitch for @Options:

@ethankusters

One of the primary reasons I think we should use the @Options container is to further enforce that the directives that go in an @Options are explicitly out-of-the-ordinary and a clear departure from the norm. All other directives should be creating content on the page and, thus, outside of a container. This is the same reason that metadata directives belong in a container.

Introducing @DeviceFrame as a separate directive now introduces confusion for all other container directive use in DocC articles. The user needs to ask – "Is this a special directive that sets configuration for a specific set of child directives or this a container directive that holds markup?"

I still think we should explore alternative syntax for adding configuration to directives. Maybe something like this:

@Image(source: "sloth") {
   My image caption here.
}
.deviceFrame(phone)

which would solve a lot of the documentation and scalability issues we've discussed.

But I think the correct intermediate solution here is to add this as a parameter instead of breaking the mental model of how container directives work in DocC articles.