Closed alademann closed 10 years ago
Hello Aaron and thanks a lot for taking the time to have a look.
First, let me remind this project is veryyyyyy young. I have only worked on it for a couple of hours with the help of @valeriangalliat, and I'd never written a single line of Node before it, so it's pretty much a crash test here! That being said, since https://github.com/eoneill/sassdoc has been dead for like 2 years... I thought it might be a good idea to give it a try.
Anyway.
I am willing to include variable documentation. I think it's a perfectly valid request. I'd like to see something like this:
// @var {type} name (value) - description
$var: my variable;
This would be a good way to keep in sync with parameter parsing but I am not convinced with the value being between curved braces. I feel like it should have a stronger place in the line. We'll have to think about it.
I need to implement @example
but for that, I need to turn the whole thing into a real parser, and not some shitty regular expressions.
Eventually I want to end up with this:
// @example
// clamp(10, 1, 5)
// // -> 5
Or something like that.
Fully okay with @since
. Will be very easy to add by the way.
I'll update this comment when I get time.
Cool, thanks Hugo!
Hi all,
Thanks Aaron for all these suggestions! This will bring SassDoc to a new level for sure - and Hugo was just searching improvements ideas. :)
About the variable documentation, I don't see the need to include the variable name and default value in the docstring. The actual variable declaration just below is giving the name and default value, so why not just display it (like the function/mixin signatures)?
// @var {type} description
$var: default value;
I think we could epurate @param
in the same way. Since there may be multiple @param
s it's more readable to keep the name, but the default value can still be deducted from the signature.
Maybe the @public
annotation can be ommited too, since we can see the !global
in the variable signature.
It's interesting to add a documentation format for (nested) maps. I don't like the JSDoc way of doing this:
/**
* @param {Object} options
* @param {String} options.foo
* @param {Number} options.bar
*/
I'd see something more like YAML (this is not valid YAML though):
// @var {map}
// base:
// default: {type} description
// text: {type} description
// bg: {type} description
// bd: {type} description
// success: {type} description
// ...
$panel: (...);
But I'm not really sure about it, it will be really verbose.
Another possibility is to add comments directly in the map declaration:
// @var {map} description
$panel: (
'base': (
'default': ( // @key {type} description
'text': $gray-dark, // @key {type} description
'bg': #fff, // @key {type} description
'bd': #ddd, // @key {type} description
),
),
);
This would require to parse the whole map to extract the structure, but it's more lightweight to define.
Otherwise, if we display the real variable declaration in the documentation, simple comments like above even without the @key
would be sufficient to understand the purpose of the commented keys. For example the Kohana framework's API browser displays the full source code of a function below the formatted docblock, and I find this really handy. A similar thing for variable declarations including comments can be sufficient.
The @example
annotation is a bit tricky for the syntax highlighting. We can want it to highlight Sass or HTML depending on the cases. I think it's fair to assume an @example
on a mixin or function will be in Sass, but will contain HTML when applied on a CSS class.
If needed, an optional lang
attribute could be added after @example
to set the right syntax highlighting, but I don't really see an use case for this (if the contextual syntax above is implemented).
Also since the "long description" is interpreted as Markdown, it's also possible to define the code samples within the description instead of adding @example
. What do you think?
@usedin
is interesting, but I'm not sure about the naming. @see
would be more standard, but the semantic is not exactly the same.
@support
should be @supports
to keep it consistant with @returns
, @throws
, @depends
, etc.
I like the idea of documenting BEM classes.
Like the name and value for variables, we can also get the class name by looking the line after the docblock, it's redundant to add it after the annotation. But maybe it can be tricky to find it in the selector for more complex cases?
@valeriangalliat thanks for taking a look!
Variables Agreed on all points. the name of the var shouldn't need to be included in the docblock
Maps
I think adding the @key
declaration directly in the map is a more ideal solution
Examples
This is low priority IMO - I'm much more interested in the @depends
/ BEM documentation.
Meta
This is also low priority - but i'm cool with changing @support
to @supports
.
BEM This is the piece that the SassDocJS tool demonstrates nicely - but it is a poorly coded solution, and I've yet to be able to get it up and running in a local environment.
I think the base class would still need to be declared in the docblock as I showed in my example - but what you're saying is that the "name" could be omitted for the others if the base class was used as reference like so?
// @base panel
.panel { }
// @element
.panel-body {}
In this example - are you saying that the .panel-body
class would be reference-able / defined as @element panel-body
since it starts with the class defined as a @base
?
What I mean by "reference-able" - is... will the docs be able to demonstrate a linked hierarchy and understand the difference, for instance between a @element
(nested within the @base
) and a @modifier
(additional context for a @base
OR @element
)?
If the referential integrity can still remain simply by inferring that an @element
or @modifier
with no name listed should simply be stored based on the line immediately after the docblock... I think that would work fine!
Let me know if that makes sense.
Hello.
Okay, so I got cut yesterday night. Let me come back to what I was saying.
Will be implemented under the following syntax:
// @var {type} - Description
$variable: my variable;
A few notes:
!global
flag will make the variable public, else it will be private (scoped)I want to implement this, but as I said I need a real parser for this. Regular expressions won't do the trick. That being said, writing a parser is complicated, but I'll give it a try.
For now, I suggest you join them in the description since it is being parsed in Markdown. I haven't tried but I'd say that:
// Here is the description or whatever
// clamp(10, 0, 5);
// -> 5
... should work.
I like the idea but not the name. Perhaps @see
would be enough for me. That being said, I want to have something like that so I'm okay.
Agreed. Will be implemented.
I am not willing to add this. This is very anecdotal and should belong in the description in my opinion. Unless someone has a very strong reason to add such a feature, this is a nope.
Okay, I like that. Although I don't think it's possible to do that with regular expressions right now so until we have a dedicated parser, this probably won't work.
I have hard time seeing the difference between @depends
and @requires
. As far as possible, I'd like to keep only one, unless both are serving strictly different purposes.
I'll open separated issues for all this stuff. Please move discussion to specific issues.
@HugoGiraudel awesome - thanks!
Hugo...
I'm curious if it would be possible to support non-mixin/function documentation? I'm needing something like http://sassdocjs.com/doc/, but that repo's code is borderline un-maintainable IMO.
The function and mixin parsing is awesome - and I need that piece. But in order to document a modular front-end framework built with Sass, there are a few more pieces to the puzzle for me. (These are all just suggestions / open for discussion obviously)
First thing is... I need a way to document some basic Sass
$variables
(and maybe event some nifty Sass map-typed variable traversal).I also need to document / describe relationships / dependencies between Sass entities (classes, placeholders, ids, etc...) and entire modules (read: Sass partials) in a very large, very modular BEM/OOCSS platform.
I would propose adding the following definitions (I also understand if this needs to be broken into separate issues, but wanted to get a discussion rolling in one place):
Variables
@var {type | other type} $name (default value) - description of var
@private
means that it is scoped to a module, and combined with@public
means that it would be declared using!global
?$panel
var below)Meta
@example
- provide brief HTML implementation example@usedin
- similar to@link
- provide an example where a developer could see it being used@since
- provide a version when a specific class/function/mixin was made available@support
- list of supported browsers for a moduleModular (BEM/OOCSS) Hierarchy
@module
- define a file as a module.@base
- define a class/id as a "base" class/id for a module.@element
- define a class/id as a "element" class/id for a "base" class/id@modifier {type}
- define a class/id as a "modifier" class/id for a "base" or "element" class/id{type}
would be "open-ended", but would be something likevariant
orstate
, for example.@depends
- similar to@requires
- except this would create a link to an external@module
(or even some JS) that is not implied via the declared@base
/@element
/@modifier
syntax.@depends
lines (see$panel
var example below)?@extends
- similar to@depends
, but this type of element would automatically extend a dependency instead of implying that the other module/component had to be used/included separately.Example
Below is an example "module" - in a platform that shows a little bit of what I'm envisioning / describing above.
sass/core/modules/_panels.scss
.Thanks so much for discussing/considering this - I'm happy to do whatever I can to contribute if you think these are valuable additions to the repo. Any other thoughts on how to make this more intuitive are most welcome and appreciated!