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

Multi-line description truncated in summary #85

Closed
letmaik opened this issue Sep 22, 2015 · 7 comments
Closed

Multi-line description truncated in summary #85

letmaik opened this issue Sep 22, 2015 · 7 comments

Comments

@letmaik
Copy link

@letmaik letmaik commented Sep 22, 2015

When I write a description sentence in two lines esdoc just uses the first line in the summary which is really odd. It should use everything until a blank line or @something comes.

@h13i32maru
Copy link
Member

@h13i32maru h13i32maru commented Sep 23, 2015

@neothemachine Thanks for this issue!
Only first line is exist in summary, this is spec of ESDoc. The spec is inspired from Android Document.

And for now, I do not have plan to support @summary tag.

@letmaik
Copy link
Author

@letmaik letmaik commented Sep 23, 2015

I think the android docs actually use the first sentence, not the first line.

Why should I violate a given max line length (let's say 80 chars) just because my first description sentence is 100 chars? It is natural to break it to two lines in that case. Please rethink it. I realize it is not a bug but a feature request.

@h13i32maru
Copy link
Member

@h13i32maru h13i32maru commented Sep 23, 2015

Oh, sorry, I was mistake.

/**
 * This is awesome function
 * and this is super cool function.
 */
function foo(){}

Currently, summary of this case is This is awesome function(first line). But do you want that summary is This is awesome function and this is super cool function.(first sentence)?

If this is your request, I will adopt the request.

@h13i32maru h13i32maru reopened this Sep 23, 2015
@letmaik
Copy link
Author

@letmaik letmaik commented Sep 23, 2015

Exactly, but be careful with the details. It may happen that the dot at the end of the sentence is missing. So you also need to cut off if there's a blank line coming or some tags start. All the examples below should work as you would expect:

/**
 * Ideally, this is all in one line.
 */
function foo(){}
/**
 * Ideally, this is all in one line, but sometimes it is just
 * a bit longer.
 */
function foo(){}
/**
 * Ideally, this is all in one line, but sometimes it is just
 * a bit longer
 * 
 * Here comes more detailed descriptions. Note I forgot the
 * dot above.
 */
function foo(){}
/**
 * Ideally, this is all in one line, but sometimes it is just
 * a bit longer
 * @return {string}
 */
function foo(){}
@h13i32maru
Copy link
Member

@h13i32maru h13i32maru commented Sep 24, 2015

Thank you. Please wait a moment. I try to fix it.

@jdfreder
Copy link

@jdfreder jdfreder commented Sep 24, 2015

👍

h13i32maru added a commit that referenced this issue Sep 27, 2015
@h13i32maru
Copy link
Member

@h13i32maru h13i32maru commented Sep 27, 2015

@neothemachine @jdfreder I published v0.3.1 that fixed this issue.

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
3 participants
You can’t perform that action at this time.