Inheritdoc behaviour

[Rob]

First, thanks for this great tool!

I wanted to inherit text from another member, and then add it to. I tried:

I tried it as a top level XML:

 /// <inheritdoc cref="Member.ref"/>
  /// <summary>
  /// Blah Blah
  /// 
  /// </summary>

XML:
     <member name="..">
            <inheritdoc cref=".."/>
            <summary>
            Blah Blah
            </summary>

But the output from the tool removes the Blah Blah and you just get the inherited text.

Tried for fun:

  /// <summary>
  /// Blah Blah
  /// <inheritdoc cref="Member.ref"/>
  /// </summary>

and got in the XML:

    </member>
        <member name="M:..">
            <summary>
            Blah Blah
            <inheritdoc cref="Member.ref"/>
            </summary>

Same result.

Is this intentional behaviour?

Many Thanks

[Paillat Laszlo]

Hello, this is indeed intentional, VS intellisense actually does the same, inheritdoc works as "all or nothing" you can't inherit just a part of the documentation and add/override stuff :(

[Rob]

Ahh i thought so, just wanted to clarify that because i saw what was in the xml.

Thanks for your quick response.

One thing of note, when i use Types in DefaultDocumentationGeneratedPages, then I get enums which are members of classes in separate .md pages which is not what I really want, I want them to be inside their classes .md file. For instance:

    public class MouseEventArgs
    {
        [System.Flags]
        public enum MouseButtons { ..}

You get a .md file for MouseEventArgs.md, and a .md file for MouseButtons.

If I instead use:

Classes,Delegates,Structs,Interfaces

Then all the enums end up in the index.md file.

It would be nice for an option to allow the enums of a class to stay in their .md file.

thanks

[Paillat Laszlo]

It is not specific for enum types but you can change where the nested types are displayed with this option:

<DefaultDocumentationNestedTypeVisibilities>: where to show nested types, Namespace by default. You can give multiple value separated by a ,.

• Namespace: nested types will appear on their namespace page
• DeclaringType: nested types will appear on their declaring type page

[Rob]

Thanks, sorry for bothering you!

I tried DeclaringType, and the enum is still being produced in a separate file.

for example:

namespace Test
{
    /// <summary>
    /// Test A
    /// </summary>
    public class TestA
    {
        /// <summary>
        /// Enum
        /// </summary>
        public enum EA { one,two,three}

    }
}

with

1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|AssemblyPageName: 
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|InvalidCharReplacement: _
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|FileNameMode: FullName
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|RemoveFileExtensionFromLinks: True
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|NestedTypeVisibilities: DeclaringType
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|GeneratedPages: Types
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|GeneratedAccessModifiers: Public, Protected
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|IncludeUndocumentedItems: False
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|IgnoreLineBreak: False
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|LinksOutputFile: 
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|LinksBaseUrl: 
1>  2022-01-14 08:35:46.6429|INFO|DefaultDocumentation|ExternLinksFiles:

produces:

Test_TestA.md
Test_TestA_EA.md

What i'd really like is for the enum to be inside Test_TestA.md, as a separate section called enums (like you have constructors, properties, methods).

I also tried it with Namespace:

1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|InvalidCharReplacement: _
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|FileNameMode: FullName
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|RemoveFileExtensionFromLinks: True
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|NestedTypeVisibilities: Namespace
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|GeneratedPages: Types
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|GeneratedAccessModifiers: Public, Protected
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|IncludeUndocumentedItems: False
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|IgnoreLineBreak: False
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|LinksOutputFile: 
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|LinksBaseUrl: 
1>  2022-01-14 08:39:38.3757|INFO|DefaultDocumentation|ExternLinksFiles:

and saw the same output - two files.

Thank you for your patience!

[Paillat Laszlo]

Ah yes sorry I wasn't explicit enough, you actually need both the NestedTypeVisibilities as DeclaringType and GeneratedPages as Classes,Delegates,Structs,Interfaces.

NestedTypeVisibilities tells the generation where the nested types should be put, GeneratedPages tells which kinds should have their own page or else they will be inlined directly in their parent page.

[Rob]

Hi, that sorted it, thanks.

I've ended up using

    <DefaultDocumentationGeneratedPages>Classes,Delegates,Interfaces</DefaultDocumentationGeneratedPages>
    <DefaultDocumentationFileNameMode>FullName</DefaultDocumentationFileNameMode>
    <DefaultDocumentationRemoveFileExtensionFromLinks>True</DefaultDocumentationRemoveFileExtensionFromLinks>
    <DefaultDocumentationExternLinksFiles>docexternlinks.txt</DefaultDocumentationExternLinksFiles>
    <DefaultDocumentationGeneratedAccessModifiers>Public,Protected</DefaultDocumentationGeneratedAccessModifiers>
    <DefaultDocumentationNestedTypeVisibilities>DeclaringType</DefaultDocumentationNestedTypeVisibilities>

And with a little moving around of the structures into classes (I had some just in the namespace, and they appeared in index.md) there was only a few) both the structures and enums now appear in the class .md file, which is what i wanted.

Thanks you for your help. This is a great tool.

I'll close it now.

[Rob]

The only thing I'd add it would be useful to have a way of forcing a Struct or Enum, which is in a namespace on its own, to a file, while letting strutcs/enums which are in a class/interface to stay with that class or interface.

[Paillat Laszlo]

hum I didn't plan on having that level of customization for which item has its own page or not but maybe it is possible to add it in the new json configuration format that is coming, I will check how it would work.