@todo from file level annotations getting overwritten

[PixelZombie]

trafficstars

Hey there,

I just noticed that when I add a @todo inside of file level annotations, all documented items in that file share the same todos which is good! But when a single @todo in my documented item is added, the todos from the file level annotation aren't rendered anymore. Does this work as intended? I suggest to display the file level todos even if the documented item has todos of it's own.

Sample:

//// ---------------------------------------------------------------------------------------------
/// First level annotation
/// @group css-properties
/// 
/// @todo data type check
/// @todo value amount check
/// @todo rgba-fallback?
//// ---------------------------------------------------------------------------------------------

///
@mixin without-todo {...}

Output

TODO's
data type check
value amount check
rgba-fallback?

/// @todo another one
@mixin with-todo {...}

Output

TODO's
another one

My suggestion:

TODO's
data type check
value amount check
rgba-fallback?
another one

Cheers!

[valeriangalliat]

Well it behaves as documented on File-level annotations.

Warning: when an item has an annotation that has already been defined on the poster, it overrides it. It is not merged with the one from the poster, it purely replaces it.

However there's maybe place for improvement here… this needs some reflection but the annotations with mutliple: true should maybe add to the poster comment ones instead of overriding? Would it cause any problem with other annotations @SassDoc/owners?

Technically this should be done in CDocParser; testing for annotations[key].multiple and merging if true.

[pascalduez]

But then how would one do to use the current behavior ? Removing all poster inherited values and only add new one(s).

[valeriangalliat]

I don't think it's really a problem for most annotations, it often make more sense that annotations with multiple: truebe merged between item and file-level.

However it might not be the case for all multiple annotations, for example I'm not sure @author should be merged this way… I'd expect an item @author to override the file-level one. We could have an overridable property on annotations to have precise control over this. It would be meaningful only for multiple annotations, would be true by default, but we could set it to false for (at least) @author. CDocParser should then be updated to support overridable and do the right thing when meging item and file-level annotations.

[pascalduez]

As discussed on Slack, yes, makes sense.

[KittyGiraudel]

I'd like @FWeinb opinion.

[FWeinb]

I like it :+1:

[KittyGiraudel]

I'm cool then. If someone wants to tackle it, be my guest. :)

[FWeinb]

I implemented it in #410 but changed the name from overwriteable to overwritePoster to be a little bit more expressiv. Please review @SassDoc/owners

[pascalduez]

Great work @FWeinb

Should this be released as a patch or rather in 2.2 ? Somehow it is a change of the current behavior, even if it shouldn't break.

[valeriangalliat]

I see this as a feature more than a bugfix, so I'd say 2.2.