Пример #1
0
        private ParameterEntry FormatParameterEntry(
            int currentMaxWidth,
            ArgumentUsageInfo info,
            ArgumentSetUsageInfo setInfo,
            List <IEnumArgumentType> inlineDocumentedEnums)
        {
            List <ColoredMultistring> enumValueEntries = null;

            if (inlineDocumentedEnums?.Count > 0)
            {
                enumValueEntries = inlineDocumentedEnums.SelectMany(
                    e => GetEnumValueEntries(currentMaxWidth - _options.SectionEntryHangingIndentWidth, e))
                                   .ToList();

                if (enumValueEntries.Count == 0)
                {
                    enumValueEntries = null;
                }
            }

            return(new ParameterEntry
            {
                Syntax = FormatParameterSyntax(info, setInfo, inlineDocumentedEnums?.Count > 0),
                Description = FormatParameterDescription(info, setInfo),
                // TODO: Let section hanging indent override.
                InlineEnumEntries = enumValueEntries
            });
        }
Пример #2
0
        private ColoredMultistring FormatParameterSyntax(ArgumentUsageInfo info, ArgumentSetUsageInfo setInfo, bool enumsDocumentedInline)
        {
            var longNameSyntax = info.GetSyntax(_options.Arguments, enumsDocumentedInline);

            var formattedSyntax = new List <ColoredString>();

            // First add parameter's short name (if it has one and if it's supposed to be here).
            if (_options.Arguments.ShortName == ArgumentShortNameHelpMode.IncludeWithLongName &&
                !string.IsNullOrEmpty(info.ShortName) &&
                !string.IsNullOrEmpty(setInfo.DefaultShortNamePrefix))
            {
                formattedSyntax.Add(new ColoredString(setInfo.DefaultShortNamePrefix + info.ShortName, _options.Arguments?.ArgumentNameColor));
                formattedSyntax.Add(", ");
            }

            formattedSyntax.Add(new ColoredString(longNameSyntax, _options.Arguments?.ArgumentNameColor));

            return(new ColoredMultistring(formattedSyntax));
        }
Пример #3
0
        private ColoredMultistring FormatParameterDescription(
            ArgumentUsageInfo info,
            ArgumentSetUsageInfo setInfo)
        {
            var builder = new ColoredMultistringBuilder();

            List <ColoredString> defaultValueContent = null;

            if (_options.Arguments.DefaultValue != ArgumentDefaultValueHelpMode.Omit &&
                !string.IsNullOrEmpty(info.DefaultValue))
            {
                defaultValueContent = new List <ColoredString>
                {
                    new ColoredString(Strings.UsageInfoDefaultValue, _options.Arguments.MetadataColor),
                    " ",
                    info.DefaultValue
                };
            }

            if (_options.Arguments.DefaultValue == ArgumentDefaultValueHelpMode.PrependToDescription &&
                defaultValueContent != null)
            {
                builder.Append("[");
                builder.Append(defaultValueContent);
                builder.Append("]");
            }

            if (_options.Arguments.IncludeDescription && !string.IsNullOrEmpty(info.Description))
            {
                if (builder.Length > 0)
                {
                    builder.Append(" ");
                }

                builder.Append(info.Description);
            }

            var metadataItems = new List <List <ColoredString> >();

            if (_options.Arguments.DefaultValue == ArgumentDefaultValueHelpMode.AppendToDescription &&
                defaultValueContent != null)
            {
                metadataItems.Add(defaultValueContent);
            }

            // Append parameter's short name (if it has one).
            if (_options.Arguments.ShortName == ArgumentShortNameHelpMode.AppendToDescription &&
                !string.IsNullOrEmpty(info.ShortName) &&
                !string.IsNullOrEmpty(setInfo.DefaultShortNamePrefix))
            {
                metadataItems.Add(new List <ColoredString>
                {
                    new ColoredString(Strings.UsageInfoShortForm, _options.Arguments.MetadataColor),
                    " ",
                    new ColoredString(setInfo.DefaultShortNamePrefix + info.ShortName, _options.Arguments?.ArgumentNameColor)
                });
            }

            if (metadataItems.Count > 0)
            {
                if (builder.Length > 0)
                {
                    builder.Append(" ");
                }

                builder.Append("[");
                builder.Append(metadataItems.InsertBetween(new List <ColoredString> {
                    ", "
                }).Flatten());
                builder.Append("]");
            }

            return(builder.ToMultistring());
        }
Пример #4
0
        /// <summary>
        /// Find all enum types that need to be documented, and sort out whether they
        /// should be documented inline in their usage sites or coalesced into a
        /// toplevel section.
        /// </summary>
        /// <param name="setInfo">Argument set usage info.</param>
        /// <param name="inlineDocumented">Receives a dictionary of inline-documented
        /// enum types.</param>
        /// <param name="separatelyDocumented">Receives an enumeration of enum types
        /// that should be separately documented.</param>
        private void GetEnumsToDocument(ArgumentSetUsageInfo setInfo,
                                        out IReadOnlyDictionary <ArgumentUsageInfo, List <IEnumArgumentType> > inlineDocumented,
                                        out IEnumerable <IEnumArgumentType> separatelyDocumented)
        {
            // Find all enum types in the full type graph of the argument set; this
            // "type map" will map each unique enum type to the one or more arguments that
            // reference it.
            var enumTypeMap = GetAllArgumentTypeMap(setInfo, t => t is IEnumArgumentType);

            // Construct a dictionary for us to register inline-documented types; it will
            // map from argument to the list of enum types that should be inline documented
            // with it.
            var id = new Dictionary <ArgumentUsageInfo, List <IEnumArgumentType> >();

            // Construct a list for us to register separately-documented types; it should
            // be a simple, unique list of enum types.
            var sd = new List <IEnumArgumentType>();

            // Look through all enum types.
            foreach (var pair in enumTypeMap)
            {
                var enumType = (IEnumArgumentType)pair.Key;

                // Figure out how many times it shows up.
                var instanceCount = pair.Value.Count;

                // Skip any types that somehow show up multiple times.
                if (instanceCount == 0)
                {
                    continue;
                }

                // Decide whether to separately document; we start with the assumption
                // that we *won't* separately document.
                bool shouldSeparatelyDocument = false;

                // If we've been asked to unify the summary of enums with multiple references,
                // then check the instance count.
                if (_options.EnumValues.Flags.HasFlag(ArgumentEnumValueHelpFlags.SingleSummaryOfEnumsWithMultipleUses) &&
                    instanceCount > 1)
                {
                    shouldSeparatelyDocument = true;
                }

                // If we've been asked to unify the summary of command enums, then check if this
                // enum is a command enum.
                if (_options.EnumValues.Flags.HasFlag(ArgumentEnumValueHelpFlags.SingleSummaryOfAllCommandEnums) &&
                    ArgumentUsageInfo.IsCommandEnum(enumType.Type))
                {
                    shouldSeparatelyDocument = true;
                }

                // If we're separately documenting, then add it into that list.
                if (shouldSeparatelyDocument)
                {
                    sd.Add(enumType);
                }

                // Otherwise, add it to the inline-documented map.
                else
                {
                    // Make sure to add it for each argument referencing it.
                    foreach (var arg in pair.Value)
                    {
                        if (!id.TryGetValue(arg, out List <IEnumArgumentType> types))
                        {
                            types   = new List <IEnumArgumentType>();
                            id[arg] = types;
                        }

                        types.Add(enumType);
                    }
                }
            }

            inlineDocumented     = id;
            separatelyDocumented = sd;
        }