Empty comments #84

Closed
HugoGiraudel opened this Issue Jul 9, 2014 · 5 comments

Comments

Projects
None yet
2 participants
@HugoGiraudel
Member

HugoGiraudel commented Jul 9, 2014

Currently, only comments beginning with /** and ending with */ are parsed. That means a comment beginning with /* won't be treated as documentation.

/**
 * Documentation
 */

/*
 * Not documentation
 */

/* Not documentation either */

// Certainly not documentation

I think everybody is perfectly fine with this right now. That's how most documentation systems work, including the popular JavaDoc.

Now, running our test, here is what data looks like.

[ { unknown:
     [ [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object] ] } ]
[ { unknown: [ [Object], [Object], [Object], [Object] ],
    undefined: [ [Object], [Object] ] },
  { unknown: [ [Object] ], undefined: [ [Object], [Object] ] },
  { unknown: [ [Object], [Object] ] },
  { unknown:
     [ [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object] ],
    undefined: [ [Object], [Object] ] },
  { unknown: [ [Object], [Object], [Object], [Object], [Object] ],
    undefined: [ [Object] ] } ]
[ { variable: [ [Object], [Object], [Object] ] },
  { function: [ [Object], [Object], [Object], [Object], [Object] ] },
  { mixin: [ [Object] ] },
  { mixin:
     [ [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object] ] } ]
[ { unknown: [ [Object] ] } ]
[ { unknown: [ [Object], [Object], [Object], [Object] ] },
  { unknown:
     [ [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object] ] },
  { unknown: [ [Object], [Object], [Object], [Object] ],
    undefined: [ [Object], [Object] ] },
  { unknown: [ [Object] ], undefined: [ [Object], [Object] ] },
  { unknown: [ [Object], [Object] ] },
  { unknown:
     [ [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object] ],
    undefined: [ [Object], [Object] ] },
  { unknown: [ [Object], [Object], [Object], [Object], [Object] ],
    undefined: [ [Object] ] },
  { variable: [ [Object], [Object], [Object] ] },
  { function: [ [Object], [Object], [Object], [Object], [Object] ] },
  { mixin: [ [Object] ] },
  { mixin:
     [ [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object],
       [Object] ] },
  { unknown: [ [Object] ] } ]

This is a mess, and it is partially my fault. I use /** */ everywhere. Every time I want to write a comment about something, I go /** */ for instance:

/**
 * Item count
 */
.header__item-count {
  float: right;
  margin: 0;
}

This is perfectly fine, right? I should be able to use the type of comment I want wherever I want, especially since it doesn't anything to do with SassDoc in this example.

Now, we still get a lot of things documented because of this, that are then stripped (basically not displayed) once in the view.

My point is: a documented item without any annotation registered should simply be removed before heading to the view. An item with no annotation is obviously not a documentation. We should not have to move this crap around.

Any thought?

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 9, 2014

Member

Compromise: Lets ignore them in SassDoc.

Member

FWeinb commented Jul 9, 2014

Compromise: Lets ignore them in SassDoc.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 9, 2014

Member

I am okay with cleaning up data on SassDoc's side rather than ScssCommentParser's side. What I don't want is moving all this —basically useless— stuff to the view.

Member

HugoGiraudel commented Jul 9, 2014

I am okay with cleaning up data on SassDoc's side rather than ScssCommentParser's side. What I don't want is moving all this —basically useless— stuff to the view.

@HugoGiraudel HugoGiraudel added the 1.0 label Jul 9, 2014

@HugoGiraudel HugoGiraudel added this to the 1.0 milestone Jul 9, 2014

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 9, 2014

Member

Okay. Fixed the issue with returning context : undefined in sasscommentparser@0.0.19. Will create a PR to ignore context : 'unknown'

Member

FWeinb commented Jul 9, 2014

Okay. Fixed the issue with returning context : undefined in sasscommentparser@0.0.19. Will create a PR to ignore context : 'unknown'

@FWeinb FWeinb assigned HugoGiraudel and unassigned FWeinb Jul 9, 2014

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 9, 2014

Member

I assigned @HugoGiraudel to update the view.

Member

FWeinb commented Jul 9, 2014

I assigned @HugoGiraudel to update the view.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment