文档注释。 #821

J-邓恩

GRBL 通常内容丰富、清晰且写得很好，但有时它们可能会令人困惑。前段时间我曾说过，一旦我对代码库有了更清晰的了解，我就会提供一些建议。

当我遇到这些问题时，我会使用这个问题作为建议的下拉框。

protocol.c
// 循环重新初始化。步进路径应该完全继续，就好像什么都没发生一样。
// 循环重新初始化。步进路径应该在它停止的地方继续。

由于有减速、停止和加速，切割将不会“完全像什么都没发生过一样”。

香奈儿

@J-Dunn: 我想我毕竟是人。:) 请注意，所有评论都不会针对每个微小的更改进行更新。有些被忽略了，在新的上下文中可能意味着不同的东西。无论如何，这些评论通常是针对我的。我对我编写的每一段代码都进行了大量评论，尤其是在我的日常工作中。

J-邓恩

我也是。节省大量时间来破译六个月前我认为很明显的东西。然而，评论的水平才是让 GRBL 如此愉快地工作的原因。

希望一些被忽视或对熟悉代码的人来说显而易见的事情对其他人来说会变得更加清楚。令我困惑的主要部分在 stepper.c 中，通常非常有用，但有些术语混淆。我仍然不完全确定我已经足够清楚地对主要块提出完全有效的建议。我可能会进一步编辑我现在拥有的内容。

有时句子有点难以理解，我必须多读几遍才能明白我的意思。在某些情况下，我一直试图澄清语言。这是来自 motion_control.c 的一个

// NOTE: This is the primary gateway to the grbl planner. All line motions, including arc line 
// segments, must pass through this routine before being passed to the planner. The seperation of
// mc_line and plan_buffer_line is done primarily to place non-planner-type functions from being
// in the planner and to let backlash compensation or canned cycle integration simple and direct.

// NOTE: This is the primary gateway to the grbl planner. All line motions, including arc line 
// segments, must pass through this routine before being passed to the planner. The seperation of
// mc_line and plan_buffer_line is done primarily to place non-planner-type functions outside
// the planner and to make backlash compensation and canned cycle integration simple and direct.

香奈儿

@J-Dunn：好吧，我不能让企业公然将东西复制到闭源控制器中变得太容易。

J-邓恩

是的，这是一个缺点，就像在 ADSL 路由器中广泛使用 Linux 一样，但它是一把双刃剑。如果您想利用那些可能为 OSS 做出贡献的人，那么推迟他们或让他们花费大部分可用时间来尝试掌握代码没有多大意义。

那是开玩笑，还是你想留下有缺陷的评论来迷惑敌人？

J-邓恩

mc_homing_cycle

// Perform homing cycle to locate and set machine zero. Only '$H' executes this command.
// NOTE: There should be no motions in the buffer and Grbl must be in an idle state before
// executing the homing cycle. This prevents incorrect buffered plans after homing.
void mc_homing_cycle()

但是 mc_probe_cycle 说：

  // Finish all queued commands and empty planner buffer before starting probe cycle.
  protocol_buffer_synchronize();

描述表明他们应该做同样的事情，但 $H 不同步。过目不忘？

香奈儿

@J-Dunn: 正如您已经发现的那样，代码已经非常紧密且相当复杂。如果不深入了解一切如何协同工作，我认为任何数量的评论都不会帮助破译它在做什么。我会先把事情搁置一旁，直到下一个项目有更多的空间来呼吸和抽象出来。

J-邓恩

嗯，我的经验 FWIW 是我花了很多时间逐行挑选代码，在 stepper.c 中更清晰的注释会节省很多精力。那里的东西很好，但缺乏结构中块/段/步骤划分的清晰轮廓。我常常不清楚指的是几个缓冲区中的哪一个，有时步骤和段之间似乎有些不清晰。

但如果你想离开它，我会在本地做笔记

X3ms蛇

我认为更清晰的评论是一种进步。J-Dunn
试图做的事情有什么问题吗？

2015-10-15 20:33 GMT+01:00 J-Dunn notifications@github.com：

嗯，我的经验 FWIW 是我花了很多时间
逐行挑选代码，在 stepper.c 中更清晰的注释会节省
很多精力。那里的东西很好，但缺乏
结构中块/段/步骤划分的清晰轮廓。我常常不清楚指的是几个缓冲区中的哪一个，有时步骤和段之间
似乎有些不清晰。

但如果你想离开它，我会在本地做笔记

—
直接回复此电子邮件或在 GitHub
#821（评论）上查看。

Com os melhores cumprimentos,
Vinicius Silva

香奈儿

@X3msnake: Grbl 目前丰富而简洁的评论在开源社区中已经很少见了。有什么不好的@J-Dunn正在做，但就我而言，这不是时间和精力的良好投资。使注释完美无缺。

X3ms蛇

行。

No dia sexta-feira, 16 de outubro de 2015, Sonny Jeon <
notifications@github.com
javascript:_e(%7B%7D,’cvml’,’notifications@github.com’);> escreveu:

@X3msnake https://github.com/X3msnake：Grbl 目前丰富而
简洁的评论在开源社区中已经很少见了。有
什么不好的@J-Dunn https://github.com/J-Dunn正在做，但
在我看来，这不是一项很好的时间和精力投资。使注释完美无缺
。

—
直接回复此电子邮件或在 GitHub
#821（评论）上查看。

Com os melhores cumprimentos,
Vinicius Silva

chamnit已完成关闭 2015 年 10 月 16 日

文档注释。#821

注释