The Wayback Machine - https://web.archive.org/web/20210815103141/https://github.com/dotnet/command-line-api/issues/833
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Help - line wrap #833

Open
drmcghee opened this issue Mar 30, 2020 · 6 comments
Open

Help - line wrap #833

drmcghee opened this issue Mar 30, 2020 · 6 comments

Comments

@drmcghee
Copy link

@drmcghee drmcghee commented Mar 30, 2020

In my code I have a multiple line summary (comments) for my main method.

when I run my executable and ask for help myapp.exe --help the summary gets line wrapped.
I would like for each line in my summary to have a new line between.

I have tried every mechanism to make this work to no joy (also looked in the dragonfruit code a little) but couldn't find a quick fix.

 /// <summary>
 /// line 1
 /// line2
 /// </summary>
@marcusturewicz
Copy link
Contributor

@marcusturewicz marcusturewicz commented May 25, 2020

Unless I'm missing something, but it's not as simple as that. You might have a summary that spans multiple lines (for code readability) but you really want the newlines removed in the help description, e.g.:

/// <summary>
/// This is a really long summary because my app is really great and I want
/// to say lots of great things about it in this summary so people will use it
/// all the time and then I will get famous.
/// </Summary>

So how do you to tell DragonFruit that it should keep the newline? You could use a special character e.g. -:

/// <summary>
/// - This is a really great app
/// - You can use it for all the things
/// </Summary>

But then you should support multiple levels of indentation, bullet points and so forth? Is this really worth it? For instance, node -h and npm -h don't have a description and dotnet -h has a super small description : Execute a .NET SDK command.

@drmcghee
Copy link
Author

@drmcghee drmcghee commented Jun 4, 2020

I don't think it needs to be complicated. just look for a newline? I don't think there is any need for detailed formatting in comments but I do see the need for line returns

@marcusturewicz
Copy link
Contributor

@marcusturewicz marcusturewicz commented Jun 4, 2020

But the newline won't work in every case - if you have a long Summary and have used newlines for code readability, you want these removed in the help command.

@asasine
Copy link
Contributor

@asasine asasine commented Nov 5, 2020

.NET XML documentation supports the <para> tag for explicitly specifying paragraphs. When it is compiled, separate paragraphs are separated by line breaks.

https://docs.microsoft.com/dotnet/csharp/programming-guide/xmldoc/para

@yringler
Copy link

@yringler yringler commented Nov 10, 2020

tags do not create newlines in --help from dragon fruit. That would be great if they did!

@yringler
Copy link

@yringler yringler commented Nov 10, 2020

I ran the test, and saw that if there was only one para tag it did create the new line? But multiple it didn't, because it uses Value?
I don't have time to look into this further, but I did open a PR (only to my forks master, I don't want to clutter up the offical repo with a PR if I don't intend on following up), and anyone can feel free to take a look and base further work in this area on that.

I do think proper handling of doc string tags (list, para, etc) would help create nice help messages, which are nice to have.
yringler/pull/1/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants