tags

[icoach]

Hi!

Nice work, I have been thinking about CSS Doc concept for some time,
but I am no programmer, so I haven´t tried to implement it. I went
through the spec and it looks promissing. I would suggest tag
@component.

When I code CSS, I often use encapsulated "components", such as
breadcrumb navigation, rating component, multi combo boxes, ...

I think that section tag is not accurate in this case.

Martin

[mot]

Hi Martin,

thanks for you feedback. The examples you give look like sections for
me, I often put breadcrumb and other "widgets" or "boxes" etc. areas /
parts into sections or subsections. I have not run into any problems
with that until today.

Tom

[in...@martinstanek.cz]

Well, it think it depends on the point of view... it is subjective.
Section is more like header or body to me, then subsection is f.e. left
panel. Each section can contain multiple elements, however component
should be css style for one separate component.

As I said, it is subjective, so never mind. I was just a thought :)

Have a nice day.

Martin

[mot]

okay, section is not a secion of a hypertext document, it's a section
of the CSS file. so maybe that is the point of view that makes a
change.

the thought is good because for me I'm not so shure about having
subsections. we already had a discussion about that subsection /
subsubsection topic here in the list but not a real clue on it. maybe
cssdoc should offer some tags that can be used more "subjective" for
writers to organize their styles.

your idea infact is a nice feedback because when writing styles for
parts of a site s section somehow seems to be "too broad" to label
certrain rules that are bound to a specific wideget or component.

tom

2009/8/8 <in...@martinstanek.cz>:

[Mike West]

On Aug 8, 2009, at 10:32 AM, mot <art...@googlemail.com> wrote:

>> maybe
>> cssdoc should offer some tags that can be used more "subjective" for
>> writers to organize their styles.

Instead of diving down into ever-lengthening prefixes (sections,
subsections, subsubsections, and the logically necessary subsubsub-
and subsubsubsubsections), I'd suggest defining a generic way of
expressing hierarchy. "Packages" or "Sections" or "Components" or
"Widgets", the name is unimportant, but the concept is valuable.

Something like:

/**
* Reset stuff
* ...
* @package myproject_reset
*/
...

/**
* Base code used by all myproject's widgets
* @package myproject_widgets
*/
.widget {
...
}

/**
* Widget 1's special code
* @package myproject_widgets_widget1
*/
#widget1 {
...
}
#widget1 .head { ... }
#widget1 .body { ... }
#widget1 .foot { ... }

This makes sense to me, as it expresses the separateness of the reset
code block and the widget code blocks, while at the same time
demarcating the `widget1` section as a "child" of the `widget`
section. This allows you to build arbitrary hierarchy into your
packages/components/whatever through naming convention.

Building a naming convention into the spec (e.g.
`/([a-z]+)(-[a-z]+)+/`) would allow tools to "read" the hierarchy
information right from the package names, which strikes me as a good
way of exposing the data for use in rendering the documentation.

Additionally, note that the PHPDoc implementation doesn't require
"packageend" comments, opting instead to group everything in the
document into the last package mentioned. I rather think this makes
more sense than the currently specified cssdoc behavior, as it reduces
the burden on the author of the CSS document... properly nesting the
CSS is hard enough without thinking about nesting the comments too!

-Mike