update documentation for composability

[deepu105]

trafficstars

This is based on discussion in https://github.com/yeoman/yeoman/issues/1582

The composability feature is great and I guess it has many use cases, but the current documentation here doesnt seem sufficient to use this feature effectively, more documentation with some samples would be great,some of the areas that can be covered are as below

consider generators below

generator-foo has methods initializing, prompting, default, writing and end generator-bar has methods initializing, prompting, default, writing, install and end

1. when generator-foo composes generator-bar in the method initializing to do a task, what is the run loop order of the final context, does all the methods of generator-bar run inside the initializing method of generator-foo ? these kind of explanation will be good so that people can optimize run order when composing
2. while composing with two generators if there is a file which is modified by both how does the conflict mechanism work, what is the best practice in such cases
3. when generator-foo composes generator-bar in the method initializing to do a task, how can composed generator-bar reuse some common methods from the parent generator-foo which is defined as helper methods
4. what are the general best practices to be followed while composing generators
5. what is the best way to dynamically compose a generator, i.e for example when user is running generator-foo scans for certain generators which are installed and composes them dynamically at run time, this seems to work currently as i have done this, but not sure if there is a best practice

** some other areas in documentation that can be improved **

1. when using prompts how to effectively do a loop using same questions again, say for example asking for a entity fields, so same question needs to be repeated untill user selects no
2. when writing util or helper methods how to access the running generator context from which the method is invoked? this keyword might not work as method could be triggered from another context

cc @SBoudrias

[deepu105]

And one more thing which is not mentioned anywhere in the docs

done = this.async();
.........

done();

this is seen in the sample generators and from stack overflow found that this will be handled by yeoman even if we dont declare this, what does this exactly do and what are the use cases fro declaring this if yeoman handles them for all methods anyway?

[eddiemonge]

@deepu105 that last comment is already asked in #164

[deepu105]

Yes and its 2 years old :( guys yeoman is just awesome but needs more documentation. I know how tough it is to maintain docs but without enough documentation its just hard to do some stuff properly. We had to find out so many things by trial and error and still not sure if we are doing it properly

Sorry that im complaining but thats just coz of the love towards yeoman to see it becoming better :) hope you understand On 24 Feb 2016 08:55, "Eddie Monge" [email protected] wrote:

@deepu105 https://github.com/deepu105 that last comment is already asked in #164 https://github.com/yeoman/yeoman.github.io/issues/164

— Reply to this email directly or view it on GitHub https://github.com/yeoman/yeoman.github.io/issues/595#issuecomment-187993211 .

[eddiemonge]

I agree that maintaining docs is hard, especially when you aren't paid to do it. If you want to take on that then please feel free to. Pull requests are always welcome.

[deepu105]

I can relate to you very well. I would love to do docs but the problem is I dont understand yeoman enough in the first place to do that, that is the reason I opened this issue in the first place trying to figure how these stuff work. If someone can shed some light on those here I can try to do PRs On 24 Feb 2016 10:07, "Eddie Monge" [email protected] wrote:

I agree that maintaining docs is hard, especially when you aren't paid to do it. If you want to take on that then please feel free to. Pull requests are always welcome.

— Reply to this email directly or view it on GitHub https://github.com/yeoman/yeoman.github.io/issues/595#issuecomment-188012782 .