Multi-line description truncated in summary #85

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

Comments

Projects
None yet
3 participants
@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

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Sep 23, 2015

Member

@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.

Member

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

This comment has been minimized.

Show comment
Hide comment
@letmaik

letmaik 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.

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

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Sep 23, 2015

Member

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.

Member

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

This comment has been minimized.

Show comment
Hide comment
@letmaik

letmaik 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(){}

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

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Sep 24, 2015

Member

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

Member

h13i32maru commented Sep 24, 2015

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

@jdfreder

This comment has been minimized.

Show comment
Hide comment

👍

@h13i32maru

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Sep 27, 2015

Member

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

Member

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