/// <summary> /// Renders the <see cref="ExceptionDoc"/> element to string containing the markup provided by <paramref name="markupProvider"/> /// </summary> /// <remarks> /// Builds the link with the reference according to the <c>cref</c> attribute value. The value represents the Documentation ID /// that can be matched to the information got during the code analysis or to build the link to MS API reference for the "MS objects". /// First, it tries to resolve the <see cref="Member"/> in code being documented (internal link). If not successful, tries to look for /// the <c>cref</c> (Documentation ID) in the MS API documentation if allowed/available (see <see cref="MsApiDocEngine"/> for details) /// <para> /// The link text is the the name of linked entity when using internal <see cref="IMarkupProvider.Link(string,net.adamec.dev.markupdoc.CodeModel.Member)"/> /// or the <c>cref</c> without the leading type information when rendering . /// When the link is not constructed ("target unknown"), the <c>cref</c> value without the leading type information is rendered in italic /// </para> /// <para> /// The <exception> element is then rendered as <see cref="IMarkupProvider.DescriptionListItem"/> where ///<c>Term</c> is the link and <c>Description</c> is the fully trimmed element content. /// Important: it returns description list item, so must be encapsulated on higher level !!! /// </para> /// </remarks> /// <param name="markupProvider"><see cref="IMarkupProvider"/> allowing using the markup within the rendered content</param> /// <param name="member">Code model <see cref="Member"/> to render the XML Documentation Comment for</param> /// <param name="trim">Flag whether to (full) trim the rendered content</param> /// <returns>Rendered content of <exception> element of XML Documentation Comments. /// Important: it returns description list item, so must be encapsulated on higher level !!!</returns> ///<seealso cref="MsApiDocEngine"/> /// <seealso cref="MsApiDocOptions"/> protected override string RenderElement(IMarkupProvider markupProvider, Member member, bool trim = true) { //for exception always render both Ref(link if available) AND content //content var content = base.RenderElement(markupProvider, member, trim); //ref string exceptionRef; if (member.Root.AllMembersByDocId.TryGetValue(Ref, out var refMember)) { exceptionRef = markupProvider.Link(refMember.Name, refMember); } else { //Try to get the MS API link from reference var msLink = MsApiDocEngine.GetLink(Ref); //Got the MS link, so use external link // ReSharper disable once ConvertIfStatementToConditionalTernaryExpression if (msLink != null) { exceptionRef = markupProvider.ExternalLink(Ref.Substring(2), msLink); } else { //No link - Ref without leading "ref type" exceptionRef = markupProvider.Italic(Ref.Substring(2)); } } //output return(markupProvider.DescriptionListItem(exceptionRef, content)); }
/// <summary> /// Renders the element having the <c>cref</c> attribute to string containing the markup provided by <paramref name="markupProvider"/> /// </summary> /// <remarks> /// Builds the link with the reference according to the <c>cref</c> attribute value. The value represents the Documentation ID /// that can be matched to the information got during the code analysis or to build the link to MS API reference for the "MS objects". /// First, it tries to resolve the <see cref="Member"/> in code being documented (internal link). If not successful, tries to look for /// the <c>cref</c> (Documentation ID) in the MS API documentation if allowed/available (see <see cref="MsApiDocEngine"/> for details) /// <para> /// The link text is the rendered trimmed content of the tag if available, /// the name of linked entity when using internal <see cref="IMarkupProvider.Link(string,net.adamec.dev.markupdoc.CodeModel.Member)"/> /// or the <c>cref</c> without the leading type information when rendering <see cref="IMarkupProvider.ExternalLink"/>. /// When the link is not constructed ("target unknown"), the <c>cref</c> value without the leading type information is rendered in italic /// </para> /// </remarks> /// <param name="markupProvider"><see cref="IMarkupProvider"/> allowing using the markup within the rendered content</param> /// <param name="member">Code model <see cref="Member"/> to render the XML Documentation Comment for</param> /// <param name="trim">Flag whether to (full) trim the rendered content</param> /// <returns>Rendered content of element of XML Documentation Comments</returns> ///<seealso cref="MsApiDocEngine"/> /// <seealso cref="MsApiDocOptions"/> protected override string RenderElement(IMarkupProvider markupProvider, Member member, bool trim = true) //used for links { // ReSharper disable once RedundantArgumentDefaultValue var content = base.RenderElement(markupProvider, member, true); //always trim content for links if (string.IsNullOrEmpty(Ref)) { return(content); } //Return Ref to existing member as link, if available. If no content provided, use the member's name if (member.Root.AllMembersByDocId.TryGetValue(Ref, out var refMember)) { return(markupProvider.Link(!string.IsNullOrEmpty(content) ? content : refMember.Name, refMember)); } //Try to get the MS API link from reference var msLink = MsApiDocEngine.GetLink(Ref); //Got the MS link, so return external link if (msLink != null) { return(markupProvider.ExternalLink(!string.IsNullOrEmpty(content) ? content : Ref.Substring(2), msLink)); } //No link, return content if available otherwise Ref without leading "ref type" return(!string.IsNullOrEmpty(content) ? content : markupProvider.Italic(Ref.Substring(2))); }