Imported Upstream version 5.2.0.179

Former-commit-id: a536d4f20e27294d8bbc2184d75f3a22364f7ba1

external/api-doc-tools/mdoc/Mono.Documentation/ecmadoc.cs

@@ -0,0 +1,331 @@
+//
+// ecmadoc.cs
+//
+// Author:
+//   Jonathan Pryor  <jpryor@novell.com>
+//
+// Copyright (c) 2010 Novell, Inc. (http://www.novell.com)
+//
+// Permission is hereby granted, free of charge, to any person obtaining
+// a copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to
+// permit persons to whom the Software is furnished to do so, subject to
+// the following conditions:
+//
+// The above copyright notice and this permission notice shall be
+// included in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+//
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Xml;
+using System.Xml.Linq;
+
+using Monodoc;
+using Mono.Documentation;
+
+using Mono.Options;
+using Mono.Rocks;
+
+namespace Mono.Documentation
+{
+	public class MDocUpdateEcmaXml : MDocCommand
+	{
+		string file = "CLILibraryTypes.xml";
+		List<string> directories;
+		Dictionary<string, HashSet<string>> libraries = new Dictionary<string, HashSet<string>>();
+
+		public override void Run (IEnumerable<string> args)
+		{
+			string current_library = "";
+
+			var options = new OptionSet () {
+				{ "o|out=", 
+					"{FILE} to generate/update documentation within.\n" + 
+					"If not specified, will process " + file + ".\n" +
+					"Set to '-' to skip updates and write to standard output.",
+					v => file = v },
+				{ "library=",
+					"The {LIBRARY} that the following --type=TYPE types should be a part of.",
+					v => current_library = v },
+				{ "type=",
+					"The full {TYPE} name of a type to copy into the output file.",
+					v => AddTypeToLibrary (current_library, v) },
+			};
+			directories = Parse (options, args, "export-ecma-xml", 
+					"[OPTIONS]+ DIRECTORIES",
+					"Export mdoc documentation within DIRECTORIES into ECMA-format XML.\n\n" +
+					"DIRECTORIES are mdoc(5) directories as produced by 'mdoc update'.");
+			if (directories == null || directories.Count == 0)
+				return;
+
+			Update ();
+		}
+
+		void AddTypeToLibrary (string library, string type)
+		{
+			HashSet<string> types;
+			if (!libraries.TryGetValue (library, out types))
+				libraries.Add (library, types = new HashSet<string> ());
+			types.Add (type.Replace ('/', '.').Replace ('+', '.'));
+		}
+
+		void Update ()
+		{
+			Action<string> creator = file => {
+				XDocument docs = LoadFile (this.file);
+
+				var seenLibraries = new HashSet<string> ();
+
+				UpdateExistingLibraries (docs, seenLibraries);
+				GenerateMissingLibraries (docs, seenLibraries);
+
+				SortLibraries (docs.Root);
+				SortTypes (docs.Root);
+
+				using (var output = CreateWriter (file)) {
+					foreach (var node in docs.Nodes ()) {
+						if (node.NodeType == XmlNodeType.Element || node.NodeType == XmlNodeType.Text)
+							continue;
+						node.WriteTo (output);
+					}
+					docs.Root.WriteTo (output);
+					output.WriteWhitespace ("\r\n");
+				}
+			};
+			MdocFile.UpdateFile (this.file, creator);
+		}
+
+		static XDocument LoadFile (string file)
+		{
+			if (file == "-" || !File.Exists (file))
+				return CreateDefaultDocument ();
+
+			var settings = new XmlReaderSettings {
+				DtdProcessing = DtdProcessing.Parse
+			};
+			using (var reader = XmlReader.Create (file, settings))
+				return XDocument.Load (reader);
+		}
+
+		static XDocument CreateDefaultDocument ()
+		{
+			return new XDocument (
+					new XComment (" ====================================================================== "),
+					new XComment (" This XML is a description of the Common Language Infrastructure (CLI) library. "),
+					new XComment (" This file is a normative part of Partition IV of the following standards: ISO/IEC 23271 and ECMA 335 "),
+					new XComment (" ====================================================================== "),
+					new XDocumentType ("Libraries", null, "CLILibraryTypes.dtd", null),
+					new XElement ("Libraries"));
+		}
+
+		static XmlWriter CreateWriter (string file)
+		{
+			var settings = new XmlWriterSettings {
+				Indent              = true,
+				IndentChars         = "\t",
+				NewLineChars        = "\r\n",
+				OmitXmlDeclaration  = true,
+			};
+
+			if (file == "-")
+				return XmlWriter.Create (Console.Out, settings);
+
+			settings.Encoding = new UTF8Encoding (false);
+			return XmlWriter.Create (file, settings);
+		}
+
+		void UpdateExistingLibraries (XDocument docs, HashSet<string> seenLibraries)
+		{
+			foreach (XElement types in docs.Root.Elements ("Types")) {
+				XAttribute library = types.Attribute ("Library");
+				HashSet<string> libraryTypes;
+				if (library == null || !libraries.TryGetValue (library.Value, out libraryTypes)) {
+					continue;
+				}
+				seenLibraries.Add (library.Value);
+				var seenTypes = new HashSet<string> ();
+				foreach (XElement type in types.Elements ("Type").ToList ()) {
+					XAttribute fullName = type.Attribute ("FullName");
+					string typeName = fullName == null
+						? null
+						: XmlDocUtils.ToEscapedTypeName (fullName.Value);
+					if (typeName == null || !libraryTypes.Contains (typeName)) {
+						continue;
+					}
+					type.Remove ();
+					seenTypes.Add (typeName);
+					types.Add (LoadType (typeName, library.Value));
+				}
+				foreach (string typeName in libraryTypes.Except (seenTypes))
+					types.Add (LoadType (typeName, library.Value));
+			}
+		}
+
+		void GenerateMissingLibraries (XDocument docs, HashSet<string> seenLibraries)
+		{
+			foreach (KeyValuePair<string, HashSet<string>> lib in libraries) {
+				if (seenLibraries.Contains (lib.Key))
+					continue;
+				seenLibraries.Add (lib.Key);
+				docs.Root.Add (new XElement ("Types", new XAttribute ("Library", lib.Key),
+							lib.Value.Select (type => LoadType (type, lib.Key))));
+			}
+		}
+
+		XElement LoadType (string type, string library)
+		{
+			foreach (KeyValuePair<string, string> permutation in GetTypeDirectoryFilePermutations (type)) {
+				foreach (string root in directories) {
+					string path = Path.Combine (root, Path.Combine (permutation.Key, permutation.Value + ".xml"));
+					if (File.Exists (path))
+						return FixupType (path, library);
+				}
+			}
+			throw new FileNotFoundException ("Unable to find documentation file for type: " + type + ".");
+		}
+
+		// type has been "normalized", which (alas) means we have ~no clue which
+		// part is the namespace and which is the type name, particularly
+		// problematic as types may be nested to any level.
+		// Try ~all permutations. :-)
+		static IEnumerable<KeyValuePair<string, string>> GetTypeDirectoryFilePermutations (string type)
+		{
+			int end = type.Length;
+			int dot;
+			while ((dot = type.LastIndexOf ('.', end-1)) >= 0) {
+				yield return new KeyValuePair<string, string> (
+						type.Substring (0, dot), 
+						type.Substring (dot+1).Replace ('.', '+'));
+				end = dot;
+			}
+			yield return new KeyValuePair<string, string> ("", type.Replace ('.', '+'));
+		}
+
+		static XElement FixupType (string path, string library)
+		{
+			var type = XElement.Load (path);
+
+			XAttribute fullName   = type.Attribute ("FullName");
+			XAttribute fullNameSp = type.Attribute ("FullNameSP");
+			if (fullNameSp == null && fullName != null) {
+				type.Add (new XAttribute ("FullNameSP", fullName.Value.Replace ('.', '_')));
+			}
+			if (type.Element ("TypeExcluded") == null)
+				type.Add (new XElement ("TypeExcluded", "0"));
+			if (type.Element ("MemberOfLibrary") == null) {
+				XElement member = new XElement ("MemberOfLibrary", library);
+				XElement assemblyInfo = type.Element ("AssemblyInfo");
+				if (assemblyInfo != null)
+					assemblyInfo.AddBeforeSelf (member);
+				else
+					type.Add (member);
+			}
+
+			XElement ai = type.Element ("AssemblyInfo");
+
+			XElement assembly = 
+				XElement.Load (
+						Path.Combine (
+							Path.Combine (Path.GetDirectoryName (path), ".."), 
+							"index.xml"))
+				.Element ("Assemblies")
+				.Elements ("Assembly")
+				.FirstOrDefault (a => a.Attribute ("Name").Value == ai.Element ("AssemblyName").Value &&
+						a.Attribute ("Version").Value == ai.Element ("AssemblyVersion").Value);
+			if (assembly == null)
+				return type;
+
+			if (assembly.Element ("AssemblyPublicKey") != null)
+				ai.Add (assembly.Element ("AssemblyPublicKey"));
+
+			if (assembly.Element ("AssemblyCulture") != null)
+				ai.Add (assembly.Element ("AssemblyCulture"));
+			else
+				ai.Add (new XElement ("AssemblyCulture", "neutral"));
+
+			// TODO: assembly attributes?
+			// The problem is that .NET mscorlib.dll v4.0 has ~26 attributes, and
+			// importing these for every time seems like some serious bloat...
+			var clsDefAttr = assembly.Elements ("Attributes").Elements ("Attribute")
+				.FirstOrDefault (a => a.Element ("AttributeName").Value.StartsWith ("System.CLSCompliant"));
+			if (clsDefAttr != null &&
+					ai.Elements ("Attributes").Elements ("Attribute")
+					.FirstOrDefault (a => a.Element ("AttributeName").Value.StartsWith ("System.CLSCompliant")) == null) {
+				var dest = ai.Element ("Attributes");
+				if (dest == null)
+					ai.Add (dest = new XElement ("Attributes"));
+				dest.Add (clsDefAttr);
+			}
+
+			return type;
+		}
+
+		static void SortLibraries (XContainer libraries)
+		{
+			SortElements (libraries, (x, y) => x.Attribute ("Library").Value.CompareTo (y.Attribute ("Library").Value));
+		}
+
+		static void SortElements (XContainer container, Comparison<XElement> comparison)
+		{
+			var items = new List<XElement> ();
+			foreach (var e in container.Elements ())
+				items.Add (e);
+			items.Sort (comparison);
+			for (int i = items.Count - 1; i > 0; --i) {
+				items [i-1].Remove ();
+				items [i].AddBeforeSelf (items [i-1]);
+			}
+		}
+
+		static void SortTypes (XContainer libraries)
+		{
+			foreach (var types in libraries.Elements ("Types")) {
+				SortElements (types, (x, y) => {
+						string xName, yName;
+						int xCount, yCount;
+
+						GetTypeSortName (x, out xName, out xCount);
+						GetTypeSortName (y, out yName, out yCount);
+
+						int c = xName.CompareTo (yName);
+						if (c != 0)
+							return c;
+						if (xCount < yCount)
+							return -1;
+						if (yCount < xCount)
+							return 1;
+						return 0;
+				});
+			}
+		}
+
+		static void GetTypeSortName (XElement element, out string name, out int typeParamCount)
+		{
+			typeParamCount = 0;
+			name = element.Attribute ("Name").Value;
+
+			int lt = name.IndexOf ('<');
+			if (lt >= 0) {
+				int gt = name.IndexOf ('>', lt);
+				if (gt >= 0) {
+					typeParamCount = name.Substring (lt, gt-lt).Count (c => c == ',') + 1;
+				}
+				name = name.Substring (0, lt);
+			}
+		}
+	}
+}