Missing --full option in Engines Guide?

[sepastian]

In https://github.com/rails/rails/blob/master/guides/source/engines.md, under "Generating an engine", the command to create the engine reads:

$ rails plugin new blorgh --mountable

Just below, the text explains the --full option and how it affects the newly created engine.

Shouldn't the command to create the new engine include --full? The command would then become:

$ rails plugin new blorgh --mountable --full

[senny]

These options are exclusive, meaning you can only pass one of them:

Both options will generate an engine. The difference is that --mountable will create the engine in an isolated namespace, whereas --full will create an engine that shares the namespace of the main app.

Here is a StackOverflow post that explains the difference http://stackoverflow.com/questions/6118905/rails-3-1-engine-vs-mountable-app

I agree that the documentation in the guides is not very explicit that you can pass only --full or --mountable. It would be great if you submit a pull request to make it more explicit.

[sepastian]

Not only does it not become clear that --full and --mountable are mutually exclusive. What was confusing for me, reading the guide for the first time and following along from top to bottom, was that the text talks only about the --full option, without ever mentioning --mountable. But then, a bit further down, when creating the engine with rails plugin, the --mountable option pops up out of nowhere and is used instead of --full. That was what confused me.

Everything became clear after reading the whole guide. But since this is a guide after all, people are probably trying things out as they are reading along. And doing so, using --mountable without proper introduction could be confusing.

(On the same topic, the naming of --full seems a bit unlucky, given that its functionality is a subset of --mountable. Full means full, there's nothing one can add on top of full.)

But that's really just details, all good now, thanks for the reply.

I will try to submit a pull request when I find the time.

[senny]

@sepastian I agree the naming of --full can be confusing however I don't think this is true:

given that its functionality is a subset of --mountable. Full means full, there's nothing one can add on top of full.

Where do you see --full as a subset? Both --mountable and --full generate a complete engine. The difference is how they are integrated into a rails application. --mountable engines will isolated while --full engines are integrated.

[sepastian]

The edgeguide on engines says that --mountable does what --full does, but will add something on top:

The --mountable option tells the generator that you want to create a "mountable" and namespace-isolated engine. This generator will provide the same skeleton structure as would the --full option, and will add:

• Asset manifest files (application.js and application.css)
• A namespaced ApplicationController stub
• A namespaced ApplicationHelper stub
• A layout view template for the engine
• (and so on)

But as I said, I think that's really just details...

[robin850]

@sepastian : Actually, these things are added to a mountable engine because as its name stands, it should be mounted into an application so they avoid conflicts between the engine and the application in which it is mounted.

[senny]

The guide is still labeled "work in progress" and I think we all agree that it could be improved. Pull Requests to clarify the options and improve the structure are welcome.