lme4/lme4 — pull request #165 by singmann (2013-12-21 14:29:12+00:00)
Title: Add refit argument to anova.merMod + documentation (Issue #141)

Pull request offering the first solution sketched in Issue #141, it simply adds a refit argument to anova.merMod. This allows one to decide whether or not to refit objects of class `lmerMod` with ML when passing them to the anova method.

The code does the following:
- The default behavior remains the same: models are refitted.
- If models are actucally refitted, a message is thrown (this is new).
- If refitting is turned off and the models are inconsistently fitted (some REML, some ML), a warning is thrown. (This should perhaps produce an error instead of a warning).

```
fm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
fm2 <- lmer(Reaction ~ Days + (Days || Subject), sleepstudy)

anova(fm1, fm2) # refits with message.

anova(fm1, fm2, refit = FALSE) # doesn't refit.

fm2b <- lmer(Reaction ~ Days + (Days || Subject), sleepstudy, REML=FALSE)

anova(fm1, fm2) # refits with message.

anova(fm1, fm2b, refit = FALSE) # doesn't refit but produces a warning.
```

Additionally I added the following to the documentation (`merMod-class.Rd`):
- The usage part of the anova method (`\S3method`) + documentation of its arguments.
- A new section (`S3 methods`) listing the documented S3 methods and what they are doing (text basically taken from the `lme4.0` documentation), as suggested in the second row of `lmer.R`.

Please let me know if this is okay as is, or if I should change certain things.