Revit .NET API: InternalDefinition.SetAllowVaryBetweenGroups Two More Times

Last time, we talked about InternalDefinition.SetAllowVaryBetweenGroups(...) and especially about its Document argument.  Wondered what it would be really about?  Suggested doing an experiment about it.

We finally got a moment and did an experiment.  Here is the test code.

var docs = CachedApp.Documents.ToList<Document>();
string info = string.Empty;
Document doc1 = docs[0]; info += "Doc1: " + doc1.PathName + "\n";
Document doc2 = docs[1]; info += "Doc2: " + doc2.PathName + "\n";
var def1 = FindDef(doc1, "Occupant");
var def2 = FindDef(doc2, "Occupant");
info += string.Format("VAG in Doc1: {0}\n", def1?.VariesAcrossGroups);
info += string.Format("VAG in Doc2: {0}\n", def2?.VariesAcrossGroups);
SetVAG(def1, doc1, true);
info += string.Format("VAG in Doc1: {0}\n", def1?.VariesAcrossGroups);
info += string.Format("VAG in Doc2: {0}\n", def2?.VariesAcrossGroups);
SetVAG(def1, doc2, false);
info += string.Format("VAG in Doc1: {0}\n", def1?.VariesAcrossGroups);
info += string.Format("VAG in Doc2: {0}\n", def2?.VariesAcrossGroups);
SetVAG(def2, doc1, true);
info += string.Format("VAG in Doc1: {0}\n", def1?.VariesAcrossGroups);
info += string.Format("VAG in Doc2: {0}\n", def2?.VariesAcrossGroups);
SetVAG(def2, doc2, false);
info += string.Format("VAG in Doc1: {0}\n", def1?.VariesAcrossGroups);
info += string.Format("VAG in Doc2: {0}\n", def2?.VariesAcrossGroups);
MessageBox.Show(info);

Here is the result.

As can be seen, the Document argument does not play any role in these test cases.  No matter which document is passed to the method (doc1 or doc2), only will the VAG of def1 that is associated with doc1 be affected in the first case; and no matter which document is passed to the method (doc1 or doc2), only will the VAG of def2 that is associated with doc2 be affected in the second case.   

Once again, what is the point of providing the Document argument in the method InternalDefinition.SetAllowVaryBetweenGroups(...)  then?  Had it better be removed to avoid any confusions?! 

What if a null document is passed into the method then?

Here are the two helper methods as used by the test code.

string SetVAG(InternalDefinition def, Document doc, bool value)
{
string info = string.Empty;
using (Transaction tr = new Transaction(doc, "Set VAG"))
{
tr.Start();
try { def.SetAllowVaryBetweenGroups(doc, value); }
catch (Exception ex) { info = ex.Message; }
tr.Commit();
}
return info;
}

InternalDefinition FindDef(Document doc, string name)
{
InternalDefinition def = null;
var pbfi = doc.ParameterBindings.ForwardIterator();
pbfi.Reset();
while (pbfi.MoveNext())
if (pbfi.Key.Name == name)
{
def = pbfi.Key as InternalDefinition;
break;
}
return def;
}

Revit Parameter Organizer has been refining to address this kind of matters ...