Suggestion: add table view for type members that have their own pages?

[IggaF]

Hi,

Maybe you can add option to present Type members (properties, methods etc.) that have separate pages (according to DefaultDocumentationGeneratedPages) to be presented in a table? Similar to Microsoft docs:

[Doraku]

Sadly there is nothing close to this in markdown syntax (can't have multiple line value in table to my knowledge in pure md) which is why I settled for the current listing. While you can use html tags to easily achieve this there is no guaranty that the markdown displayer will support it so that's why I tried to stay "md raw" (yes I know I use a html tag for relative page link but it is the only exception). To remedy this I am actually making good progress on the customization (#4) of the pages with liquid template so in a near futur you should be able to change the default template to use html tags if you know they are supported where your pages are displayed :)

[IggaF]

I meant to use extended md syntax: https://www.markdownguide.org/extended-syntax/#tables I'm aware its not supported by all md editors (its written at the link above :) ), that's why I suggested to make it optional/configurable. It just - table view is way more convenient to go over page contents, especially index page

[Doraku]

Yes but it would only work if your summaries are single line, which is not always the case for everyone :/ And I fear adding too much configuration point will transform DefaultDocumentation into what made me creates it in the first place, simplicity. That's why I prefer to go the road of custom template for this so people who wants more control can do it there. Basically for this you would have to change the default template displaying members

### Methods
{%- for item in Items -%}
***
{{ item.Link }}  
{{ item.Summary}}
{%- endfor -%}

to something like this (if you know you only have one liner summaries)

| Methods | |
| --- | --- |
{%- for item in Items -%}
| {{ item.Link }} | {{ item.Summary}} |
{%- endfor -%}

(example not contractual!, the default template will not be just that) That's the gist of it, I plan to give some example (like how to revert to the old list without the summary when displaying members) to help people start customizing but you would be able to do whatever you want.

[Onzi12]

Hi IggaF, Doraku, A tabular view will make DefaultDocumentation PERFECT! The current list view makes the page very unclear and lengthy :\

Doraku, maybe the "single line" constraint can be solved with an analysis of the summary for tags that creates new line(s): <br/> <para> </para> <para/> This way, DefaultDocumentation will know to add table-rows as needed.

What do you think?

You can read more on newline tags here: How to add a line break in C# .NET documentation

[Doraku]

hum that is quite interesting, I never noticed that VisualStudio actually ignore line break when showing intellisense :o So it would make sens to rely on <br/> and <para> for multiline summaries in DefaultDocumentation to behave the same. That would indeed fix part of the problem and kinda destroy my argument of not wanting to put html tag by default x) BUT nothing stop you to add <code> element in a summary and for markdown we definitely need a line break, making it impossible to show with markdown table syntax :( Just tried html table too and cells content is not displayed as markdown so that's a no too >_>

My new idea: only show the first line of the summary when listing member (after all this is kinda a preview documentation of the member, not the full one) so we can use markdown table without problem. Things to think about:

• you would still be able to have multiple line in the preview summary by using <br/> in your documentation and putting everyting on the same line

  /// <summary>
  /// blablabla<br/>blablabla
  /// </summary>

  blablabla blablabla

• if you use linebreak in your summary to not have long line, only the first part will be used (not sure to keep this as is or ignore ligne breaks like intellisense does :/)

  /// <summary>
  /// this line is
  /// too long
  /// </summary>

  this line is

• same applied if the first element is a para

  /// <summary>
  /// <para>yello</para>
  /// world
  /// </summary>

  yello

• skip any other tag like <code> to get the first text of the summary

  /// <summary>
  /// <code>
  /// public void WhyWouldAnyoneDoThat();
  /// </code>
  /// seriously
  /// </summary>

  seriously

Do you think this behavior would be ok?

[Onzi12]

Besides programming, I'm also a UX researcher - so let me put my UX hat first: HAT ON Ok, so let's review the behavior you suggested from the user's perspective.

The user will use DefaultDocumentation with the goal of easily creating beautiful documentation. The "single line" behavior cannot be expected beforehand, so the user will run into it (or not) someday - and will be surprised by it.

I think it's safe to assume developers want a similar experience to what they are used to from IntelliSense, And also, most likely you will never get a feature request from a user for this behavior.

If the original single-line constraint can be solved by:

1. Parsing the summary for the relevant tags
2. Ignoring code tags (as it is a real technical problem)

I would go enabling it within this limitation.

We can further learn on this issue by observing how others solved it in their documentation:
Microsoft's .NET: Multi lines are supported.
Google's Android: Multi lines are supported. Apple's IOS: Multi lines are supported.

Though I don't usually tend to, here I would go with the flow.

[Doraku]

Thanks for your inputs @Onzi12. I am all for following the decision of greater minds on this! Going with the behavior of intellisense seems the more logical indeed. The fact that they added a <para> element for xml documentation just shows that you are not supposed to take line return into account I guess. Now I am just wondering to do this the lazy way (lucky for us a single line break in markdown is ignored too, so it is a minimal code change on my side, but people would still be able to display a linebreak by putting two spaces at the end of the previous line, or two line break. Maybe this "magic" behavior could still be confusing) or put a little more effort into it (the method to display <code> and text element are the same in DefaultDocumentation. For code we want to keep line break! but for real text we remove every linebreak, forcing people to use <br/> and <para> to structure their description).

[Doraku]

small update and preview on this. I opted for a mix approached for now (line break in xml documentation are kept and replaced by <br/> element for preview). Can be tester with latest beta 0.7.4-beta2. Here is the output of one file:

DefaultEcs

DefaultEcs.System

AComponentSystem<TState,TComponent> Class

Represents a base class to process updates on a given World instance to all its components of type TComponent.

public abstract class AComponentSystem<TState,TComponent> :
DefaultEcs.System.ISystem<TState>,
System.IDisposable

Type parameters

TState
The type of the object used as state to update the system.

TComponent
The type of component to update.

Inheritance System.Object 🡒 AComponentSystem<TState,TComponent>

Implements DefaultEcs.System.ISystem<TState>, System.IDisposable

Constructors
AComponentSystem(World, IParallelRunner, int)	Initialise a new instance of the AComponentSystem<TState,TComponent> class with the given World and IParallelRunner.
AComponentSystem(World, IParallelRunner)	Initialise a new instance of the AComponentSystem<TState,TComponent> class with the given World and IParallelRunner.
AComponentSystem(World)	Initialise a new instance of the AComponentSystem<TState,TComponent> class with the given World.

Properties
IsEnabled	Gets or sets whether the current AComponentSystem<TState,TComponent> instance should update or not.
World	Gets the World instance on which this system operates.

Methods
[Dispose()](AComponentSystem_TState_TComponent__Dispose().md 'DefaultEcs.System.AComponentSystem<TState,TComponent>.Dispose()')	Does nothing.
PostUpdate(TState)	Performs a post-update treatment.
PreUpdate(TState)	Performs a pre-update treatment.
Update(TState, Span<TComponent>)	Update the given TComponent once.
Update(TState, TComponent)	Update the given TComponent once.
Update(TState)	Updates the system once. Does nothing if IsEnabled is false or if there is no component of type TComponent in the World.

[Onzi12]

My friend, it looks beautiful! Great job! I will test the beta on my API.

The file you sent behaves very well on my phone screen - supports the wrapping and long words in a user friendly way.

Any specific reason for the mixed approach?

[Doraku]

Any specific reason for the mixed approach?

I am still kinda torn on this, some intellisense behaviors just make no sense to me (you can't have multiple spaces, it will only display one). I hate this "you don't get what you type" approach and the need to rely on some balises. But maybe I am alone in expecting things to work like this and I should just listen to the voice of reason.

[IggaF]

@Doraku I've tested last beta, table view looks reallllllyyyy good. Thanks a lot :)