doc.cs

C#编译器源代码。Micorsoft开放源代码

					return null;
				}
			}
			// here we still don't consider return type (to
			// detect CS1581 or CS1002+CS1584).
			msig = new MethodSignature (oper, null, paramList);
			mis = type.FindMembers (
				MemberTypes.Method,
				BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static,
				MethodSignature.method_signature_filter,
				msig);
			if (mis.Length == 0)
				return null; // CS1574
			MemberInfo mi = mis [0];
			Type expected = mi is MethodInfo ?
				((MethodInfo) mi).ReturnType :
				mi is PropertyInfo ?
				((PropertyInfo) mi).PropertyType :
				null;
			if (returnTypeName != null) {
				Type returnType = FindDocumentedType (mc, returnTypeName, ds, cref);
				if (returnType == null || returnType != expected) {
					warningType = 1581;
					Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute `{0}'", cref);
					return null;
				}
			}
			return mis [0];
		}

		private static bool IsAmbiguous (MemberInfo [] members)
		{
			if (members.Length < 2)
				return false;
			if (members.Length > 2)
				return true;
			if (members [0] is EventInfo && members [1] is FieldInfo)
				return false;
			if (members [1] is EventInfo && members [0] is FieldInfo)
				return false;
			return true;
		}

		private static Type [] emptyParamList = new Type [0];

		//
		// Processes "see" or "seealso" elements.
		// Checks cref attribute.
		//
		private static void HandleXrefCommon (MemberCore mc,
			DeclSpace ds, XmlElement xref)
		{
			string cref = xref.GetAttribute ("cref").Trim (wsChars);
			// when, XmlReader, "if (cref == null)"
			if (!xref.HasAttribute ("cref"))
				return;
			if (cref.Length == 0)
				Report.Warning (1001, 1, mc.Location, "Identifier expected");
				// ... and continue until CS1584.

			string signature; // "x:" are stripped
			string name; // method invokation "(...)" are removed
			string parameters; // method parameter list

			// strip 'T:' 'M:' 'F:' 'P:' 'E:' etc.
			// Here, MS ignores its member kind. No idea why.
			if (cref.Length > 2 && cref [1] == ':')
				signature = cref.Substring (2).Trim (wsChars);
			else
				signature = cref;

			int parensPos = signature.IndexOf ('(');
			if (parensPos > 0 && signature [signature.Length - 1] == ')') {
				name = signature.Substring (0, parensPos).Trim (wsChars);
				parameters = signature.Substring (parensPos + 1, signature.Length - parensPos - 2);
			}
			else {
				name = signature;
				parameters = String.Empty;
			}
			Normalize (mc, ref name);

			string identifier = name;

			if (name.Length > 0 && name [name.Length - 1] == ']') {
				string tmp = name.Substring (0, name.Length - 1).Trim (wsChars);
				if (tmp [tmp.Length - 1] == '[')
					identifier = tmp.Substring (0, tmp.Length - 1).Trim (wsChars);
			}

			// Check if identifier is valid.
			// This check is not necessary to mark as error, but
			// csc specially reports CS1584 for wrong identifiers.
			string [] nameElems = identifier.Split ('.');
			for (int i = 0; i < nameElems.Length; i++) {
				string nameElem = nameElems [i];
				if (nameElem.EndsWith ("[]"))
					nameElem = nameElem.Substring (
						nameElem.Length - 2);
				if (i > 0)
					Normalize (mc, ref nameElem);
				if (!Tokenizer.IsValidIdentifier (nameElem)
					&& nameElem.IndexOf ("operator") < 0) {
					Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",
						mc.GetSignatureForError (), cref);
					xref.SetAttribute ("cref", "!:" + signature);
					return;
				}
			}

			// check if parameters are valid
			Type [] parameterTypes = emptyParamList;
			if (parameters.Length > 0) {
				string [] paramList = parameters.Split (',');
				ArrayList plist = new ArrayList ();
				for (int i = 0; i < paramList.Length; i++) {
					string paramTypeName = paramList [i].Trim (wsChars);
					Normalize (mc, ref paramTypeName);
					Type paramType = FindDocumentedType (mc, paramTypeName, ds, cref);
					if (paramType == null) {
						Report.Warning (1580, 1, mc.Location, "Invalid type for parameter `{0}' in XML comment cref attribute `{1}'", i + 1, cref);
						return;
					}
					plist.Add (paramType);
				}
				parameterTypes = plist.ToArray (typeof (Type)) as Type [];
				StringBuilder sb = new StringBuilder ();
				sb.Append ('(');
				for (int i = 0; i < parameterTypes.Length; i++) {
					Type t = parameterTypes [i];
					if (sb.Length > 1)
						sb.Append (',');
					sb.Append (t.FullName.Replace ('+', '.'));
				}
				sb.Append (')');
				parameters = sb.ToString ();
			}

			Type type = FindDocumentedType (mc, name, ds, cref);
			if (type != null
				// delegate must not be referenced with args
				&& (!type.IsSubclassOf (typeof (System.Delegate))
				|| parameterTypes.Length == 0)) {
				xref.SetAttribute ("cref", "T:" + type.FullName.Replace ("+", "."));
				return; // a type
			}

			// don't use identifier here. System[] is not alloed.
			if (RootNamespace.Global.IsNamespace (name)) {
				xref.SetAttribute ("cref", "N:" + name);
				return; // a namespace
			}

			int period = name.LastIndexOf ('.');
			if (period > 0) {
				string typeName = name.Substring (0, period);
				string memberName = name.Substring (period + 1);
				Normalize (mc, ref memberName);
				type = FindDocumentedType (mc, typeName, ds, cref);
				int warnResult;
				if (type != null) {
					MemberInfo mi = FindDocumentedMember (mc, type, memberName, parameterTypes, ds, out warnResult, cref);
					if (warnResult == 419)
						Report419 (mc, name, mi);
					else if (warnResult > 0)
						return;
					if (mi != null) {
						xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + type.FullName.Replace ("+", ".") + "." + memberName + parameters);
						return; // a member of a type
					}
				}
			}
			else {
				int warnResult;
				MemberInfo mi = FindDocumentedMember (mc, ds.TypeBuilder, name, parameterTypes, ds, out warnResult, cref);
				if (warnResult == 419)
					Report419 (mc, name, mi);
				else if (warnResult > 0)
					return;
				if (mi != null) {
					xref.SetAttribute ("cref", GetMemberDocHead (mi.MemberType) + ds.TypeBuilder.FullName.Replace ("+", ".") + "." + name);
					return; // local member name
				}
			}

			Report.Warning (1574, 1, mc.Location, "XML comment on `{0}' has cref attribute `{1}' that could not be resolved",
				mc.GetSignatureForError (), cref);

			xref.SetAttribute ("cref", "!:" + name);
		}

		static void Report419 (MemberCore mc, string memberName, MemberInfo mi)
		{
			Report.Warning (419, 3, mc.Location, 
				"Ambiguous reference in cref attribute `{0}'. Assuming `{1}' but other overloads including `{1}' have also matched",
				memberName, TypeManager.GetFullNameSignature (mi));
		}

		//
		// Get a prefix from member type for XML documentation (used
		// to formalize cref target name).
		//
		static string GetMemberDocHead (MemberTypes type)
		{
			switch (type) {
			case MemberTypes.Constructor:
			case MemberTypes.Method:
				return "M:";
			case MemberTypes.Event:
				return "E:";
			case MemberTypes.Field:
				return "F:";
			case MemberTypes.NestedType:
			case MemberTypes.TypeInfo:
				return "T:";
			case MemberTypes.Property:
				return "P:";
			}
			return "!:";
		}

		// MethodCore

		//
		// Returns a string that represents the signature for this 
		// member which should be used in XML documentation.
		//
		public static string GetMethodDocCommentName (MethodCore mc, DeclSpace ds)
		{
			Parameter [] plist = mc.Parameters.FixedParameters;
			Parameter parr = mc.Parameters.ArrayParameter;
			string paramSpec = String.Empty;
			if (plist != null) {
				StringBuilder psb = new StringBuilder ();
				foreach (Parameter p in plist) {
					psb.Append (psb.Length != 0 ? "," : "(");
					psb.Append (p.ParameterType.FullName.Replace ("+", "."));
				}
				paramSpec = psb.ToString ();
			}
			if (parr != null)
				paramSpec += String.Concat (
					paramSpec == String.Empty ? "(" : ",",
					parr.ParameterType.FullName.Replace ("+", "."));

			if (paramSpec.Length > 0)
				paramSpec += ")";

			string name = mc is Constructor ? "#ctor" : mc.Name;
			string suffix = String.Empty;
			Operator op = mc as Operator;
			if (op != null) {
				switch (op.OperatorType) {
				case Operator.OpType.Implicit:
				case Operator.OpType.Explicit:
					suffix = "~" + op.OperatorMethodBuilder.ReturnType.FullName.Replace ('+', '.');
					break;
				}
			}
			return String.Concat (mc.DocCommentHeader, ds.Name, ".", name, paramSpec, suffix);
		}

		//
		// Raised (and passed an XmlElement that contains the comment)
		// when GenerateDocComment is writing documentation expectedly.
		//
		// FIXME: with a few effort, it could be done with XmlReader,
		// that means removal of DOM use.
		//
		internal static void OnMethodGenerateDocComment (
			MethodCore mc, DeclSpace ds, XmlElement el)
		{
			Hashtable paramTags = new Hashtable ();
			foreach (XmlElement pelem in el.SelectNodes ("param")) {
				int i;
				string xname = pelem.GetAttribute ("name");
				if (xname == "")
					continue; // really? but MS looks doing so
				if (xname != "" && mc.Parameters.GetParameterByName (xname, out i) == null)
					Report.Warning (1572, 2, mc.Location, "XML comment on `{0}' has a param tag for `{1}', but there is no parameter by that name",
						mc.GetSignatureForError (), xname);
				else if (paramTags [xname] != null)
					Report.Warning (1571, 2, mc.Location, "XML comment on `{0}' has a duplicate param tag for `{1}'",
						mc.GetSignatureForError (), xname);
				paramTags [xname] = xname;
			}
			Parameter [] plist = mc.Parameters.FixedParameters;
			if (plist != null) {
				foreach (Parameter p in plist) {
					if (paramTags.Count > 0 && paramTags [p.Name] == null)
						Report.Warning (1573, 4, mc.Location, "Parameter `{0}' has no matching param tag in the XML comment for `{1}'",
							p.Name, mc.GetSignatureForError ());
				}
			}
		}

		private static void Normalize (MemberCore mc, ref string name)
		{
			if (name.Length > 0 && name [0] == '@')
				name = name.Substring (1);
			else if (Tokenizer.IsKeyword (name) && !IsTypeName (name))
				Report.Warning (1041, 1, mc.Location, "Identifier expected. `{0}' is a keyword", name);
		}

		private static bool IsTypeName (string name)
		{
			switch (name) {
			case "bool":
			case "byte":
			case "char":
			case "decimal":
			case "double":
			case "float":
			case "int":
			case "long":
			case "object":
			case "sbyte":
			case "short":
			case "string":
			case "uint":
			case "ulong":
			case "ushort":
			case "void":
				return true;
			}
			return false;
		}
	}

	//
	// Implements XML documentation generation.
	//
	public class Documentation
	{
		public Documentation (string xml_output_filename)
		{
			docfilename = xml_output_filename;
			XmlDocumentation = new XmlDocument ();
			XmlDocumentation.PreserveWhitespace = false;
		}

		private string docfilename;

		//
		// Used to create element which helps well-formedness checking.
		//
		public XmlDocument XmlDocumentation;

		//
		// The output for XML documentation.
		//
		public XmlWriter XmlCommentOutput;

		//
		// Stores XmlDocuments that are included in XML documentation.
		// Keys are included filenames, values are XmlDocuments.
		//
		public Hashtable StoredDocuments = new Hashtable ();

		//
		// Stores comments on partial types (should handle uniquely).
		// Keys are PartialContainers, values are comment strings
		// (didn't use StringBuilder; usually we have just 2 or more).
		//
		public IDictionary PartialComments = new ListDictionary ();

		//
		// Outputs XML documentation comment from tokenized comments.
		//
		public bool OutputDocComment (string asmfilename)
		{
			XmlTextWriter w = null;
			try {
				w = new XmlTextWriter (docfilename, null);
				w.Indentation = 4;
				w.Formatting = Formatting.Indented;
				w.WriteStartDocument ();
				w.WriteStartElement ("doc");
				w.WriteStartElement ("assembly");
				w.WriteStartElement ("name");
				w.WriteString (Path.ChangeExtension (asmfilename, null));
				w.WriteEndElement (); // name
				w.WriteEndElement (); // assembly
				w.WriteStartElement ("members");
				XmlCommentOutput = w;
				GenerateDocComment ();
				w.WriteFullEndElement (); // members
				w.WriteEndElement ();
				w.WriteWhitespace (Environment.NewLine);
				w.WriteEndDocument ();
				return true;
			} catch (Exception ex) {
				Report.Error (1569, "Error generating XML documentation file `{0}' (`{1}')", docfilename, ex.Message);
				return false;
			} finally {
				if (w != null)
					w.Close ();
			}
		}

		//
		// Fixes full type name of each documented types/members up.
		//
		public void GenerateDocComment ()
		{
			TypeContainer root = RootContext.Tree.Types;
			if (root.Interfaces != null)
				foreach (Interface i in root.Interfaces) 
					DocUtil.GenerateTypeDocComment (i, null);

			if (root.Types != null)
				foreach (TypeContainer tc in root.Types)
					DocUtil.GenerateTypeDocComment (tc, null);

			if (root.Parts != null) {
				IDictionary comments = PartialComments;
				foreach (ClassPart cp in root.Parts) {
					if (cp.DocComment == null)
						continue;
					comments [cp] = cp;
				}
			}

			if (root.Delegates != null)
				foreach (Delegate d in root.Delegates) 
					DocUtil.GenerateDocComment (d, null);

			if (root.Enums != null)
				foreach (Enum e in root.Enums)
					e.GenerateDocComment (null);

			IDictionary table = new ListDictionary ();
			foreach (ClassPart cp in PartialComments.Keys) {
				// FIXME: IDictionary does not guarantee that the keys will be
				//        accessed in the order they were added.
				table [cp.PartialContainer] += cp.DocComment;
			}
			foreach (PartialContainer pc in table.Keys) {
				pc.DocComment = table [pc] as string;
				DocUtil.GenerateDocComment (pc, null);
			}
		}
	}
}

#endif