Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[mdoc] Added -api-style parameter. #2333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonpryor merged 1 commit into from
Jan 7, 2016
Merged

[mdoc] Added -api-style parameter. #2333

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions mcs/tools/mdoc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ check-monodocer-dropns-classic: $(PROGRAM)
# tests the simplest --dropns case, a single class where the root namespace was dropped.
-rm -Rf Test/en.actual
$(MAKE) Test/DocTest-DropNS-classic.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic.dll --api-style=classic
$(MAKE) update-monodocer-dropns-unified
diff --exclude=.svn -rup Test/en.expected-dropns-classic-v1 Test/en.actual

Expand All @@ -186,12 +186,12 @@ check-monodocer-dropns-multi: $(PROGRAM)
$(MAKE) Test/DocTest-DropNS-unified-multitest.dll

# mdoc update for both classic and unified
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-CLASSIC) -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-UNIFIED) --dropns Test/DocTest-DropNS-unified.dll=MyFramework --dropns Test/DocTest-DropNS-unified-multitest.dll=MyFramework -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-CLASSIC) --api-style=classic -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-UNIFIED) --api-style=unified --dropns Test/DocTest-DropNS-unified.dll=MyFramework --dropns Test/DocTest-DropNS-unified-multitest.dll=MyFramework -multiassembly

# now run it again to verify idempotency
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-CLASSIC) -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-UNIFIED) --dropns Test/DocTest-DropNS-unified.dll=MyFramework --dropns Test/DocTest-DropNS-unified-multitest.dll=MyFramework -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-CLASSIC) --api-style=classic -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-UNIFIED) --api-style=unified --dropns Test/DocTest-DropNS-unified.dll=MyFramework --dropns Test/DocTest-DropNS-unified-multitest.dll=MyFramework -multiassembly

diff --exclude=.svn -rup Test/en.expected-dropns-multi Test/en.actual

Expand All @@ -204,12 +204,12 @@ check-monodocer-dropns-multi-withexisting: $(PROGRAM)
$(MAKE) Test/DocTest-DropNS-unified-multitest.dll

# mdoc update to show a pre-existing set of documents
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified.dll --dropns Test/DocTest-DropNS-unified.dll=MyFramework
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic.dll --api-style=classic
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified.dll --api-style=unified --dropns Test/DocTest-DropNS-unified.dll=MyFramework

# mdoc update for both classic and unified
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-CLASSIC) -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-UNIFIED) --dropns Test/DocTest-DropNS-unified.dll=MyFramework --dropns Test/DocTest-DropNS-unified-multitest.dll=MyFramework -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-CLASSIC) --api-style=classic -multiassembly
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual $(MULTI-UNIFIED) --api-style=unified --dropns Test/DocTest-DropNS-unified.dll=MyFramework --dropns Test/DocTest-DropNS-unified-multitest.dll=MyFramework -multiassembly

diff --exclude=.svn -rup Test/en.expected-dropns-multi-withexisting Test/en.actual

Expand All @@ -218,35 +218,35 @@ check-monodocer-dropns-delete: $(PROGRAM)
rm -Rf Test/DocTest-DropNS-classic-deletetest.dll
rm -Rf Test/DocTest-DropNS-unified-deletetest.dll
$(MAKE) Test/DocTest-DropNS-classic-deletetest.dll
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic-deletetest.dll
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic-deletetest.dll --api-style=classic
$(MAKE) Test/DocTest-DropNS-unified-deletetest.dll
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified-deletetest.dll --dropns Test/DocTest-DropNS-unified-deletetest.dll=MyFramework
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified-deletetest.dll --api-style=unified --dropns Test/DocTest-DropNS-unified-deletetest.dll=MyFramework
$(MAKE) Test/DocTest-DropNS-classic-deletetest-V2.dll
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic-deletetest.dll
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic-deletetest.dll --api-style=classic
$(MAKE) Test/DocTest-DropNS-unified-deletetest-V2.dll
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified-deletetest.dll --dropns Test/DocTest-DropNS-unified-deletetest.dll=MyFramework
$(MONO) $(PROGRAM) update --delete --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified-deletetest.dll --api-style=unified --dropns Test/DocTest-DropNS-unified-deletetest.dll=MyFramework
diff --exclude=.dvn -rup Test/en.expected-dropns-delete Test/en.actual

check-monodocer-dropns-classic-withsecondary: $(PROGRAM)
# tests case where a secondary assembly is included with a --dropns parameter
-rm -Rf Test/en.actual
$(MAKE) Test/DocTest-DropNS-classic.dll
$(MAKE) Test/DocTest-DropNS-classic-secondary.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic.dll Test/DocTest-DropNS-classic-secondary.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic.dll Test/DocTest-DropNS-classic-secondary.dll --api-style=classic
$(MAKE) update-monodocer-dropns-unified-withsecondary
diff --exclude=.svn -rup Test/en.expected-dropns-classic-withsecondary Test/en.actual

update-monodocer-dropns-unified: $(PROGRAM)
$(MAKE) Test/DocTest-DropNS-unified.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified.dll --dropns Test/DocTest-DropNS-unified.dll=MyFramework
$(MONO) $(PROGRAM) update --debug --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified.dll --api-style=unified --dropns Test/DocTest-DropNS-unified.dll=MyFramework

update-monodocer-dropns-unified-withsecondary: $(PROGRAM)
$(MAKE) Test/DocTest-DropNS-unified.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified.dll Test/DocTest-DropNS-classic-secondary.dll --dropns Test/DocTest-DropNS-unified.dll=MyFramework
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-unified.dll Test/DocTest-DropNS-classic-secondary.dll --api-style=unified --dropns Test/DocTest-DropNS-unified.dll=MyFramework

update-monodocer-dropns-classic-secondary: $(PROGRAM)
$(MAKE) Test/DocTest-DropNS-classic-secondary.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic-secondary.dll
$(MONO) $(PROGRAM) update --exceptions=all -o Test/en.actual Test/DocTest-DropNS-classic-secondary.dll --api-style=classic

check-monodocer-internal-interface: $(PROGRAM)
# Tests to make sure internal interfaces that are explicitly implemented are not documented
Expand Down
94 changes: 78 additions & 16 deletions mcs/tools/mdoc/Mono.Documentation/monodocer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,8 @@ class MDocUpdater : MDocCommand
List<AssemblyDefinition> assemblies;
readonly DefaultAssemblyResolver assemblyResolver = new DefaultAssemblyResolver();

string apistyle = string.Empty;
bool isClassicRun;
bool multiassembly;
bool delete;
bool show_exceptions;
Expand Down Expand Up @@ -282,6 +284,9 @@ public override void Run (IEnumerable<string> args)
{ "multiassembly",
"Allow types to be in multiple assemblies.",
v => multiassembly = true },
{ "api-style=",
"Denotes the apistyle. Currently, only `classic` and `unified` are supported. `classic` set of assemblies should be run first, immediately followed by 'unified' assemblies with the `dropns` parameter.",
v => apistyle = v.ToLowerInvariant ()},
};
var assemblies = Parse (p, args, "update",
"[OPTIONS]+ ASSEMBLIES",
Expand All @@ -290,7 +295,17 @@ public override void Run (IEnumerable<string> args)
return;
if (assemblies.Count == 0)
Error ("No assemblies specified.");


// validation for the api-style parameter
if (apistyle == "classic")
isClassicRun = true;
else if (apistyle == "unified") {
if (!droppedAssemblies.Any ())
Error ("api-style 'unified' must also supply the 'dropns' parameter with at least one assembly and dropped namespace.");
} else if (!string.IsNullOrWhiteSpace (apistyle))
Error ("api-style '{0}' is not currently supported", apistyle);


foreach (var dir in assemblies
.Where (a => a.Contains (Path.DirectorySeparatorChar))
.Select (a => Path.GetDirectoryName (a)))
Expand Down Expand Up @@ -1040,7 +1055,7 @@ private void CleanupFiles (string dest, HashSet<string> goodfiles)
saveDoc ();

var unifiedAssemblyNode = doc.SelectSingleNode ("/Type/AssemblyInfo[@apistyle='unified']");
var classicAssemblyNode = doc.SelectSingleNode ("/Type/AssemblyInfo[@apistyle='classic']");
var classicAssemblyNode = doc.SelectSingleNode ("/Type/AssemblyInfo[not(@apistyle) or @apistyle='classic']");
var unifiedMembers = doc.SelectNodes ("//Member[@apistyle='unified']|//Member/AssemblyInfo[@apistyle='unified']");
var classicMembers = doc.SelectNodes ("//Member[@apistyle='classic']|//Member/AssemblyInfo[@apistyle='classic']");
bool isUnifiedRun = HasDroppedAnyNamespace ();
Expand Down Expand Up @@ -1260,10 +1275,10 @@ public void DoUpdateType2 (string message, XmlDocument basefile, TypeDefinition
XmlElement mm = MakeMember(basefile, new DocsNodeInfo (null, m));
if (mm == null) continue;

if (MDocUpdater.SwitchingToMagicTypes) {
if (MDocUpdater.SwitchingToMagicTypes || MDocUpdater.HasDroppedNamespace (m)) {
// this is a unified style API that obviously doesn't exist in the classic API. Let's mark
// it with apistyle="unified", so that it's not displayed for classic style APIs
mm.SetAttribute ("apistyle", "unified");
mm.AddApiStyle (ApiStyle.Unified);
}

members.AppendChild( mm );
Expand Down Expand Up @@ -1374,7 +1389,7 @@ void DeleteMember (string reason, string output, XmlNode member, MyXmlNodeList t

bool unifiedRun = HasDroppedNamespace (type);

var classicAssemblyInfo = member.SelectSingleNode ("AssemblyInfo[@apistyle='classic']");
var classicAssemblyInfo = member.SelectSingleNode ("AssemblyInfo[not(@apistyle) or @apistyle='classic']");
bool nodeIsClassic = classicAssemblyInfo != null || member.HasApiStyle (ApiStyle.Classic);
var unifiedAssemblyInfo = member.SelectSingleNode ("AssemblyInfo[@apistyle='unified']");
bool nodeIsUnified = unifiedAssemblyInfo != null || member.HasApiStyle (ApiStyle.Unified);
Expand All @@ -1393,12 +1408,13 @@ void DeleteMember (string reason, string output, XmlNode member, MyXmlNodeList t
} else if (unifiedRun && nodeIsClassic) {
// this is a unified run, and the member doesn't exist, but is marked as being in the classic assembly.
member.RemoveApiStyle (ApiStyle.Unified);
member.AddApiStyle (ApiStyle.Classic);
Warning ("Not removing '{0}' since it's still in the classic assembly.", signature);
} else if (unifiedRun && !nodeIsClassic) {
// unified run, and the node is not classic, which means it doesn't exist anywhere.
actuallyDelete ();
} else {
if (!nodeIsClassic && !nodeIsUnified) { // regular codepath (ie. not classic/unified)
if (!isClassicRun || (isClassicRun && !nodeIsClassic && !nodeIsUnified)) { // regular codepath (ie. not classic/unified)
actuallyDelete ();
} else { // this is a classic run
Warning ("Removing classic from '{0}' ... will be removed in the unified run if not present there.", signature);
Expand Down Expand Up @@ -1654,27 +1670,37 @@ public void UpdateType (XmlElement root, TypeDefinition type)

/// <summary>Adds an AssemblyInfo with AssemblyName node to an XmlElement.</summary>
/// <returns>The assembly that was either added, or was already present</returns>
static XmlElement AddAssemblyNameToNode (XmlElement root, TypeDefinition type)
XmlElement AddAssemblyNameToNode (XmlElement root, TypeDefinition type)
{
return AddAssemblyNameToNode (root, type.Module);
}

/// <summary>Adds an AssemblyInfo with AssemblyName node to an XmlElement.</summary>
/// <returns>The assembly that was either added, or was already present</returns>
static XmlElement AddAssemblyNameToNode (XmlElement root, ModuleDefinition module)
XmlElement AddAssemblyNameToNode (XmlElement root, ModuleDefinition module)
{
Func<XmlElement, bool> assemblyFilter = x => {
var existingName = x.SelectSingleNode ("AssemblyName");
return existingName != null && existingName.InnerText == module.Assembly.Name.Name;

bool apiStyleMatches = true;
string currentApiStyle = x.GetAttribute ("apistyle");
if ((HasDroppedNamespace (module) && !string.IsNullOrWhiteSpace (currentApiStyle) && currentApiStyle != "unified") ||
(isClassicRun && (string.IsNullOrWhiteSpace (currentApiStyle) || currentApiStyle != "classic"))) {
apiStyleMatches = false;
}
return apiStyleMatches && (existingName == null || (existingName != null && existingName.InnerText == module.Assembly.Name.Name));
};

return AddAssemblyXmlNode (
root.SelectNodes ("AssemblyInfo").Cast<XmlElement> ().ToArray (),
assemblyFilter, x => WriteElementText (x, "AssemblyName", module.Assembly.Name.Name),
() => {
XmlElement ass = WriteElement (root, "AssemblyInfo", forceNewElement: true);

if (MDocUpdater.HasDroppedNamespace (module))
ass.SetAttribute ("apistyle", "unified");
ass.AddApiStyle (ApiStyle.Unified);
if (isClassicRun)
ass.AddApiStyle (ApiStyle.Classic);
return ass;
}, module);
}
Expand Down Expand Up @@ -1780,8 +1806,8 @@ static XmlElement AddAssemblyXmlNode (XmlElement[] relevant, Func<XmlElement, bo
XmlElement thisAssemblyNode = relevant.FirstOrDefault (valueMatches);
if (thisAssemblyNode == null) {
thisAssemblyNode = makeNewNode ();
setValue (thisAssemblyNode);
}
setValue (thisAssemblyNode);

if (isUnified) {
thisAssemblyNode.AddApiStyle (ApiStyle.Unified);
Expand Down Expand Up @@ -2352,7 +2378,7 @@ private static void NormalizeWhitespace(XmlElement e) {
n.ParentNode.RemoveChild(n);
}

private static bool UpdateAssemblyVersions (XmlElement root, MemberReference member, bool add)
private bool UpdateAssemblyVersions (XmlElement root, MemberReference member, bool add)
{
TypeDefinition type = member as TypeDefinition;
if (type == null)
Expand All @@ -2371,8 +2397,11 @@ private static string GetAssemblyVersion (AssemblyDefinition assembly)
return assembly.Name.Version.ToString();
}

private static bool UpdateAssemblyVersions(XmlElement root, AssemblyDefinition assembly, string[] assemblyVersions, bool add)
private bool UpdateAssemblyVersions(XmlElement root, AssemblyDefinition assembly, string[] assemblyVersions, bool add)
{
if (multiassembly)
return false;

XmlElement av = (XmlElement) root.SelectSingleNode ("AssemblyVersions");
if (av != null) {
// AssemblyVersions is not part of the spec
Expand All @@ -2389,7 +2418,7 @@ private static bool UpdateAssemblyVersions(XmlElement root, AssemblyDefinition a
e = root.OwnerDocument.CreateElement("AssemblyInfo");

if (MDocUpdater.HasDroppedNamespace (assembly)) {
e.SetAttribute ("apistyle", "unified");
e.AddApiStyle (ApiStyle.Unified);
}

root.AppendChild(e);
Expand All @@ -2398,8 +2427,8 @@ private static bool UpdateAssemblyVersions(XmlElement root, AssemblyDefinition a
var thatNode = (XmlElement) root.SelectSingleNode (thatNodeFilter);
if (MDocUpdater.HasDroppedNamespace (assembly) && thatNode != null) {
// there's a classic node, we should add apistyles
e.SetAttribute ("apistyle", "unified");
thatNode.SetAttribute ("apistyle", "classic");
e.AddApiStyle (ApiStyle.Unified);
thatNode.AddApiStyle (ApiStyle.Classic);
}

return UpdateAssemblyVersionForAssemblyInfo (e, root, assemblyVersions, add);
Expand Down Expand Up @@ -3037,6 +3066,39 @@ public static void AddApiStyle(this XmlElement element, ApiStyle style) {
if (string.IsNullOrWhiteSpace (existingValue) || existingValue != styleString) {
element.SetAttribute ("apistyle", styleString);
}

// Propagate the API style up to the membernode if necessary
if (element.LocalName == "AssemblyInfo" && element.ParentNode != null && element.ParentNode.LocalName == "Member") {
var member = element.ParentNode;
var unifiedAssemblyNode = member.SelectSingleNode ("AssemblyInfo[@apistyle='unified']");
var classicAssemblyNode = member.SelectSingleNode ("AssemblyInfo[not(@apistyle) or @apistyle='classic']");

var parentAttribute = element.ParentNode.Attributes ["apistyle"];
Action removeStyle = () => element.ParentNode.Attributes.Remove (parentAttribute);
Action propagateStyle = () => {
if (parentAttribute == null) {
// if it doesn't have the attribute, then add it
parentAttribute = element.OwnerDocument.CreateAttribute ("apistyle");
parentAttribute.Value = styleString;
element.ParentNode.Attributes.Append (parentAttribute);
}
};

if ((style == ApiStyle.Classic && unifiedAssemblyNode != null) || (style == ApiStyle.Unified && classicAssemblyNode != null))
removeStyle ();
else
propagateStyle ();
}
}
public static void AddApiStyle (this XmlNode node, ApiStyle style)
{
string styleString = style.ToString ().ToLowerInvariant ();
var existingAttribute = node.Attributes ["apistyle"];
if (existingAttribute == null) {
existingAttribute = node.OwnerDocument.CreateAttribute ("apistyle");
node.Attributes.Append (existingAttribute);
}
existingAttribute.Value = styleString;
}
public static void RemoveApiStyle (this XmlElement element, ApiStyle style)
{
Expand Down
6 changes: 6 additions & 0 deletions mcs/tools/mdoc/Test/DocTest-DropNS-classic.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ public class MyClass {
public float Hello(int value) {
return 0.0f;
}
public double OnlyInClassic {get;set;}

#if DELETETEST
public string InBoth {get;set;}
public string InBothClassic {get;set;}
Expand All @@ -20,6 +22,10 @@ public float Hello(int value) {
#endif
}

#if DELETETEST
public class TypeOnlyInClassic {}
#endif

#if DELETETEST && !V2
public class WillDelete {
public string Name {get;set;}
Expand Down
2 changes: 2 additions & 0 deletions mcs/tools/mdoc/Test/DocTest-DropNS-unified.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ public class MyClass {
public float Hello(int value) {
return 0.0f;
}
public char OnlyInUnified {get;set;}

#if DELETETEST
public string InBoth {get;set;}
public string InBothUnified {get;set;}
Expand Down
32 changes: 32 additions & 0 deletions mcs/tools/mdoc/Test/en.expected-dropns-classic-v1/MyFramework.MyNamespace/MyClass.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,5 +76,37 @@
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="OnlyInClassic" apistyle="classic">
<MemberSignature Language="C#" Value="public double OnlyInClassic { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance float64 OnlyInClassic" />
<MemberType>Property</MemberType>
<AssemblyInfo apistyle="classic">
<AssemblyVersion>0.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Double</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="OnlyInUnified" apistyle="unified">
<MemberSignature Language="C#" Value="public char OnlyInUnified { get; set; }" />
<MemberSignature Language="ILAsm" Value=".property instance char OnlyInUnified" />
<MemberType>Property</MemberType>
<AssemblyInfo apistyle="unified">
<AssemblyVersion>0.0.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Char</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
</Member>
</Members>
</Type>
Loading