cocos2dx图片闪亮

A few months ago, I announced the first draft of SassDoc, a documentation tool for Sass. What a long road it has come since then. A couple of days a back, we finally released the second major version of SassDoc, entitled Shiny Streamy Octopus. We have been working on version 2 for months and spent a few weeks in beta, letting talented people test our product only to discover it was good enough to be released. Yay!

几个月前，我宣布了SassDoc的初稿，这是Sass的文档工具。 从那以后，它走了多么漫长的路。 几天前，我们终于发布了SassDoc的第二个主要版本，名为Shiny Streamy Octopus 。 我们已经对版本2进行了几个月的研究，并花了几周的beta测试时间，让才华横溢的人们测试我们的产品，才发现它足以被发布。 好极了！

There are two reasons behind this second version of SassDoc: the first one was to clean the code base. I wrote the first draft of SassDoc mid-2014, and we’ve been working on some code of mine until then. While the code was not bad in itself, it was certainly not very scalable so we needed a much more robust base for the future. Fortunately, Valérian, Fabrice and Pascal are three very talented JavaScript developers who turned my old crappy code into a magnificent beast.

第二个版本的SassDoc背后有两个原因：第一个是清理代码库。 我在2014年中期编写了SassDoc的初稿，直到那时我们一直在研究我的一些代码。 尽管代码本身还不错，但它当然不是很可扩展，因此我们需要一个更强大的基础来应对未来。 幸运的是， Valérian ， Fabrice和Pascal是三个非常有才华JavaScript开发人员，他们将我的旧代码变成了华丽的野兽 。

The second reason to push SassDoc v2, and the most important one, is to set up a rock solid base for us to build new features. In that way, this version does not bring many new features. It mostly consists of refactoring the whole code base, fixing bugs, improving APIs, deprecating obsolete features and all that crap that you can only do on major releases because of API breaks.

推出SassDoc v2的第二个原因(也是最重要的一个原因)是为我们建立新功能奠定了坚实的基础。 这样，此版本不会带来许多新功能。 它主要包括重构整个代码库，修复错误，改进API，弃用过时的功能以及由于API中断而只能在主要版本上执行的所有操作。

So what if I gave you a quick tour as well as some hints on how to upgrade from SassDoc v1 to Shiny Streamy Octopus?

那么，如果我给您提供快速浏览以及有关如何从SassDoc v1升级到Shiny Streamy Octopus的提示，该怎么办？

新品牌 (New branding)

SassDoc started as an experiment. At the very beginning, it was a playground for me to try Node.js. Soon enough, it was not an experiment anymore and actual people were using it on actual projects, such as the folks at ThoughtBot for Neat and Bourbon, as well as the front-end teams at The Guardian and Financial Times.

SassDoc是从实验开始的 。 从一开始，我就开始尝试Node.js。 很快，这不再是实验，实际的人正在实际的项目上使用它，例如ThoughtBot for Neat和Bourbon的人们 ，以及《卫报》和《 金融时报》的前端团队。

So we decided to give branding some love for this new version. I redesigned the whole site to have beautiful docs. We had Reda Lemeden design a logo for us, and Alix Lucas create an illustration to give SassDoc some visual strength.

因此，我们决定为品牌提供一些新版本的支持。 我将整个网站重新设计为具有漂亮的文档。 我们让Reda Lemeden为我们设计了一个徽标，而Alix Lucas创造了一个插图，使SassDoc更具视觉强度。

That being said, we are well aware that not everybody will like the new branding. That’s fair enough. The site contains nothing but documentation, and the default theme can be customized. If you really don’t like the default theme, we have set everything up so you can build your own theme in a couple of minutes.

话虽如此，我们深知并非所有人都会喜欢新品牌。 这很公平。 该网站仅包含文档，并且可以自定义默认主题。 如果您真的不喜欢默认主题，那么我们已经设置了所有内容，因此您可以在几分钟内构建自己的主题。

Now, if you feel like you can improve the default theme, we would gladly merge any thorough pull request so feel free to go nuts and suggest us any change!

现在，如果您觉得可以改进默认主题，我们很乐意合并所有详尽的请求请求，以便随时发疯并建议我们进行任何更改！

API中断 (API breaks)

Let’s start with the real thing™: API breaks. Surprisingly enough, there are not as many major API changes as I first thought it would be. Depending on your project, you might have very little to nothing to change in your Sass files to transition to the new version.

让我们从Realth™开始：API中断。 令人惊讶的是，主要的API更改没有我最初想象的那么多。 根据您的项目，在Sass文件中转换为新版本时可能几乎没有更改。

不再是C型 (C-style no more)

I think the biggest change we made for the end user (a.k.a you) at this point was to deprecate C-style comments altogether. You know how I use to sell SassDoc by saying both C-style comments (/** ... */) and inline comments (///) were supported? Well this is no longer true. We decided that providing two ways to write docs was confusing and did not help much at the end of the day. Also, library writers using C-style comments would pollute users’ code with massive comment blocks, which is really not that cool.

我认为目前我们对最终用户(也就是您)所做的最大更改是完全弃用了C样式的注释。 您知道我如何通过说支持C样式注释( /** ... */ )和内联注释( /// )来出售SassDoc吗？ 好吧，这不再是真的。 我们认为，提供两种编写文档的方法会造成混乱，并且最终收效甚微。 而且，使用C样式注释的库编写者会使用大量注释块来污染用户的代码，这确实不那么酷。

To help moving from C-style to inline comments, our own Valérian wrote a little script. However pay attention! This is a raw find and replace that cannot be 100% bullet proof (actually this script cannot successfully convert file-level comments from C-style to inline). Be sure to carefully review your code to make sure everything is right.

为了帮助从C样式转换为嵌入式注释，我们自己的Valérian编写了一个小脚本。 但是要注意！ 这是原始的查找和替换，不能100％证明其正确性(实际上，此脚本无法成功将文件级注释从C样式转换为嵌入式样式)。 请务必仔细检查您的代码，以确保一切正确。

For GNU sed:

对于GNU sed：

find . -name '*.s[ac]ss' -exec sed -i 's,^/\*\*,///,;s,^  *\*\*/,,;s,^  *\*/,///,;s,^  *\*,///,' {} +

For Mac/BSD sed:

对于Mac / BSD sed：

find . -name '*.s[ac]ss' -exec sed -i ' 's,^/\*\*,///,;s,^  *\*\*/,,;s,^  *\*/,///,;s,^  *\*,///,' {} +

Windows users, I suggest you try the GNU version in a Git shell.

Windows用户，建议您在Git Shell中尝试GNU版本。

括弧默认值 (Bracketize default values)

Another important changes we made, that unfortunately cannot be automagically fixed by a simple shell script, is to use brackets ([]) rather than parentheses (()) for default values in @property and @parameter annotations (as well as their aliases of course). Until then, you would write something like this:

我们进行的另一项重要更改(不幸的是，不能通过简单的shell脚本自动修复)是对@property和@parameter批注(以及它们的别名)中的默认值使用方括号( [] )而不是括号( () )。课程)。 在此之前，您将编写如下内容：

/// @param {String} $foo ('bar') - Baz

This annotation means the documented item accepts a $foo argument, whose default value is the string bar. This does not work anymore. From now on, you have to use brackets, turning your code into:

此注释表示记录的项目接受$foo参数，其默认值为字符串bar 。 这不再起作用。 从现在开始，您必须使用方括号，将代码转换为：

/// @param {String} $foo ['bar'] - Baz

It was a bit of a tough choice to make but we encountered some parsing issues when using parentheses as wrappers. Think of default values that contain parentheses, such as function calls (e.g. length()). From time to times, our parser choked and did not grab the correct value. Long story short, we decided to go the safest way and use brackets.

做出这个选择有些困难，但是当使用括号作为包装器时，我们遇到了一些解析问题。 考虑包含括号的默认值，例如函数调用(例如length() )。 有时，我们的解析器会阻塞并且没有获取正确的值。 长话短说，我们决定采用最安全的方法并使用括号。

To convert those parentheses to brackets, Valérian (again) wrote a little script. And again, this is dummy search and replace, so be sure to review everything carefully especially since the script will convert (length($list)) to [length[$list]]. As I said, not bulletproof.

为了将这些括号转换为方括号，Valérian(再次)编写了一个小脚本。 再次，这是虚拟搜索和替换，因此请务必仔细检查所有内容，尤其是因为脚本会将(length($list))转换为[length[$list]] 。 如我所说，不是防弹。

For GNU user:

对于GNU用户：

find . -type f -name '*.s[ac]ss' -exec sed -ri '/@param|@prop/y/()/[]/' {} +

For Mac/BSD users:

对于Mac / BSD用户：

find . -type f -name '*.s[ac]ss' -exec sed -Ei ' '/@param|@prop/y/\(\)/\[\]/' {} +

Windows users, I suggest you try the GNU version in a Git shell.

Windows用户，建议您在Git Shell中尝试GNU版本。

导出目录 (Output folder)

Once, a couple of weeks ago, we had someone come over on GitHub and tell us he had wiped his entire working directory. Crap. It turns out he didn’t read the wiki (we did not have the dedicated site back then) where we warned against the destination folder being wiped out when running SassDoc. For his defense, it was not his fault entirely: we did not prompt or abort if the destination folder was not empty. I believe we messed up.

几周前，有一次，我们有人在GitHub上来，告诉我们他已经擦除了整个工作目录。 废话 事实证明，他没有阅读Wiki(当时我们没有专用站点)，在该警告中，我们警告运行SassDoc时目标文件夹将被清除。 为了他的辩护，这完全不是他的错：如果目标文件夹不为空，我们不会提示或中止。 我相信我们搞砸了。

Shortly after, we pushed something with flags to force / prompt you with this. It worked better, it prevented any incident, it made the API a bit more complex. So we went the very easy way, the one I discarded for a long time because I didn’t really like it: we made SassDoc always output its own directory (./sassdoc) at the current path, with an option (--dest) to change this location.

不久之后，我们推送了带有标志的内容以强制/提示您这样做。 它工作得更好，防止了任何事件，使API变得更加复杂。 因此，我们采用了一种非常简单的方法，因为我不太喜欢它，所以放弃了很长时间：我们使SassDoc始终在当前路径下输出其自己的目录( ./sassdoc )，并带有一个选项( --dest )更改此位置。

So, now using SassDoc has gotten much simpler. The CLI API only asks for a source folder. The destination folder can be set with --dest, and will default to ./sassdoc if omitted.

因此，现在使用SassDoc变得更加简单。 CLI API仅要求提供源文件夹。 可以使用--dest设置目标文件夹，如果省略，则默认为./sassdoc 。

To document a specific folder, such as stylesheets/, pass it as the first argument. To change the path to the destination folder such as docs/sass/, simply use the --dest option.

要记录特定的文件夹(例如stylesheets/ ，请将其作为第一个参数传递。 要更改目标文件夹(例如docs/sass/的路径，只需使用--dest选项。

sassdoc stylesheets/ --dest ./docs/sass/

新功能 (New features)

I said this version was essentially a major refactoring of the API, but we obviously took it as an opportunity to introduce new minor features.

我说过，该版本实质上是API的主要重构，但我们显然将其作为引入新的次要功能的机会。

更强大的API (More powerful API)

We’ve seen in the previous section how we tweaked the API to make everything a bit more robust (especially regarding the output folder). You will be pleased to know we also made it possible for you to define exclude patterns so you can prevent SassDoc from parsing some files and/or folders.

在上一节中，我们已经了解了如何调整API以使所有内容都更加健壮(尤其是在输出文件夹方面)。 您将很高兴知道我们还使您能够定义排除模式，从而可以防止SassDoc解析某些文件和/或文件夹。

For instance, you could intimate SassDoc to parse your stylesheets folder but to omit vendor stylesheets. Using nothing but the CLI API, that would look like this (quotes matter):

例如，您可以提示SassDoc解析样式表文件夹，而忽略供应商样式表。 除了使用CLI API外，什么都不用，看起来像这样(引号很重要)：

sassdoc stylesheets/ '!stylesheets/vendors/*'

Now you can use the configuration file to set this up in a more persistent fashion, like so:

现在，您可以使用配置文件以更持久的方式进行设置，如下所示：

exclude:
- ./stylesheets/vendors/*

Along the same lines, it is now possible to pipe a stream into SassDoc. To put it simply q , you can now run SassDoc on a file from within the console. For instance:

按照同样的思路，现在可以到管道流进SassDoc。 简而言之，您现在可以在控制台中的文件上运行SassDoc。 例如：

cat stylesheets/utils/_functions.scss | sassdoc -

It makes it easy to debug a documented Sass file, especially when using it in combination with the --parse flag which prints the SassDoc data structure as JSON:

它使调试已记录的Sass文件变得容易，尤其是与--parse标志结合使用时，该标志将SassDoc数据结构打印为JSON：

cat stylesheets/utils/_functions.scss | sassdoc --parse -

You could even run it on a file that is not on your machine, using curl. For instance, with a file hosted on GitHub:

您甚至可以使用curl在计算机上没有的文件上运行它。 例如，使用托管在GitHub上的文件：

curl https://raw.githubusercontent.com/SassDoc/sassdoc-theme-default/master/scss/utils/_functions.scss | sassdoc --parse -

Speaking of debugging, we introduced a --debug option to print information about the current setup such as SassDoc version, arguments, enabled options and everything. Especially useful when opening an issue on the repository: just put the trace printed by --debug.

说到调试，我们引入了--debug选项来打印有关当前设置的信息，例如SassDoc版本，参数，已启用的选项以及所有内容。 在存储库中打开问题时特别有用：只需放入--debug打印的跟踪。

» [DEBUG] argv: ["scss/","--debug"]
» [DEBUG] process.argv: ["node","/Users/admin/Documents/projects/sassdoc/sassdoc/bin/sassdoc","scss/","--debug"]
» [DEBUG] sassdoc version: 2.0.3
» [DEBUG] node version: 0.10.33
» [DEBUG] npm version: 2.1.9
» [DEBUG] platform: darwin
» [DEBUG] cwd: /Users/admin/Documents/projects/sassdoc/sassdoc-theme-default
» [DEBUG] env: {
"strict": false,
"file": ".sassdocrc",
"dest": "sassdoc",
"dir": "/Users/admin/Documents/projects/sassdoc/sassdoc-theme-default",
"package": {},
"themeName": "default",
"src": [
"scss/"
]
}
» [DEBUG] task: documentize
» [DEBUG] Dumping data to `sassdoc-data.json`.

更好的默认主题 (Better default theme)

We also put a lot of love into the default theme to improve it as much as we can. One important feature we added is the ability for you to use Google Analytics or basically any other tracking system in your generated docs. To do so, we introduced two extra keys to the configuration: googleAnalytics and trackingCode.

我们还将很多爱作为默认主题，以尽可能地改善它。 我们添加的一项重要功能是，您可以在生成的文档中使用Google Analytics(分析)或基本上任何其他跟踪系统。 为此，我们为配置引入了两个额外的键： googleAnalytics和trackingCode 。

The googleAnalytics property is simply a Google Analytics tracking key mapped to your site. The theme will print the relevant JavaScript snippet with your key so you can get GA tracking.

googleAnalytics属性只是映射到您网站的Google Analytics(分析)跟踪键。 该主题将使用您的密钥打印相关JavaScript代码段，以便您进行GA跟踪。

googleAnalytics: UA-XXXXX-YY

Along the same lines, the trackingCode option also helps putting some tracking system on your docs, except it’s a bit more permissive. Basically, it’s some HTML that gets printed right before closing the tag. Beware to what you put in there, of course.

同样， trackingCode选项还可以在您的文档上放置一些跟踪系统，只是允许性更高。 基本上，是一些HTML会在关闭 标签。 当然要当心什么。

trackingCode: |
<img src="http://piwik.example.org/piwik.php?idsite={$IDSITE}amp;rec=1" style="border:0" alt="" />

下一步是什么？ (What’s next?)

We have frozen SassDoc’s feature set weeks before launching version 2 in order to focus on refactoring everything without having new developments getting in the way. Now that Shiny Streamy Octopus is out, we can go back to implementing new features and we have had a lot of suggestions in the meantime. Among others:

在发布版本2之前的几周，我们冻结了SassDoc的功能集，以便专注于重构所有内容，而不会妨碍新的开发。 现在，“ Shiny Streamy Octopus”已经发布，我们可以返回实现新功能的同时，我们也有很多建议。 除其他外：

• Add ability to introduce the docs with a short to long excerpt (#256).

  增加了以简短到简短的摘录( ＃256 )介绍文档的功能。

• Add ability to define several groups for a same item as well nested groups (#135).

  增加为同一项目定义多个组以及嵌套组的功能( ＃135 )。

• Add ability to override an item’s name with a @name annotation (#296).

  添加使用@name批注( ＃296 )覆盖项目名称的功能。

• Add ability to order items by @access rather than groups in the theme (#239).

  添加通过@access而不是主题中的组来订购项目的@access ( ＃239 )。

• Add an option to assume an item is private if it starts with a _ or a - (#340).

  如果以_或- ( ＃340 )开头的项目，则添加一个选项以假定该项目是私有的。

• Autofill more things, such as default values (#304).

  自动填充更多内容，例如默认值( ＃304 )。

• Allow theme inheritance and sub-themes (#272).

  允许主题继承和子主题( ＃272 )。

I think we’ll see many more suggestions come in the next few weeks. Of course, we value feedback a lot so if you have anything to tell, please be sure to do so.

我认为我们将在接下来的几周内看到更多建议。 当然，我们非常重视反馈，因此，如果您有什么话要说，请务必这样做。

Though allow me to take this article as an opportunity to state that SassDoc is still not planning on becoming a full-front documentation system. In that way, SassDoc cannot document CSS selectors and we are not planning on adding this feature any time soon (understand v3, perhaps).

尽管允许我以此文章为契机声明SassDoc仍不打算成为一个全面的文档系统。 这样， SassDoc无法记录CSS选择器，并且我们不打算很快添加此功能(也许理解v3 )。

SassDoc intends to document Sass API and projects. We are doing this single thing, but we are trying really hard to do it right. I think we still have plenty of progress to make on that field before going on to such a large thing like CSS selectors.

SassDoc打算记录Sass API和项目。 我们正在做这件事，但我们正在努力做到正确。 我认为，在继续进行CSS选择器之类的大型工作之前，我们在该领域仍有许多进步。

Anyway, be sure to have a look at the changelog for version 2 and the official site to read the documentation. Of course, we are available to answer any of your question on Twitter; just ping @SassDoc_ or myself!

无论如何，请务必查看版本2的变更日志和官方网站以阅读文档。 当然，我们可以在Twitter上回答您的任何问题； 只是ping @SassDoc_或我自己！

翻译自: https://www.sitepoint.com/sassdoc-2-shiny-streamy-octopus/

cocos2dx图片闪亮