About @usedin

[KittyGiraudel]

From @valeriangalliat in #15:

@usedin is interesting, but I'm not sure about the naming. @see would be more standard, but the semantic is not exactly the same.

From @alademann in #11:

The only difference would be that the expected value of @see is a fully-qualified URL, and my vision of @usedin would have an expected value of a named string(s) which would leave room for the ability to cross-link modules, functions, etc... in the documentation. This would be similar to @requires - but in the reverse direction - x uses y instead of y requires x.

In the future, the generated docs could list named strings that were referenced in a @usedin declaration and show/link to all the vars, mixins and functions that are used there.

Let me know if that makes sense - or if you think we could just extend @see so that it accepts fully qualified urls or strings that would be "indexed" as named entities.

From me in #11:

Based on this asumption, we could use the same process we used for aliases. At first, I implemented @alias and @Aliased. The first says that the documented function/mixin is an alias of the function named after the alias. Meanwhile, the @Aliased dirctive was supposed to go on the main function, linking back to the alias (think of it as "aliased by").

Valérian declined the implementation, and he was definitely right to do so. In the end, we have @alias which defines if the documented function/mixin is an alias of another function/mixin. Then we post process the data to define an aliased key, which contains the name of all aliases for each function.

I suppose we could do exactly the same for used. Post-process the data, and based on the @requires directive, fill the used key for each item.

[KittyGiraudel]

If we sum up discussions about @usedin.

Since this would basically be the inverse of @requires, we don't need to implement such a directive, so nope. That being said, we can fill a usedin key for each item once we're done with parsing, based on the @requires we found.

Question is, how do we call it?

• used
• usedby
• usedBy
• usedin
• usedIn

Opinions needed.

[alademann]

I would vote for usedBy if we're strictly using this in a "requires" context - and not in a "this component is used in this module, or in this layout".

[KittyGiraudel]

Added in both branches.