Empty comments

[KittyGiraudel]

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]

Compromise: Lets ignore them in SassDoc.

[KittyGiraudel]

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.

[FWeinb]

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

[KittyGiraudel]

We should update view to clean my now useless safeguards:

• https://github.com/SassDoc/SassDoc/blob/master/view/templates/documentation/index.html.swig#L18
• https://github.com/SassDoc/SassDoc/blob/master/view/templates/includes/partials/sidebar.html.swig#L16

[FWeinb]

I assigned @HugoGiraudel to update the view.