Clojurescript - Om 组件的 Codox 文档答案

【问题标题】：Clojurescript - Codox documentation for Om componentsClojurescript - Om 组件的 Codox 文档
【发布时间】：2015-03-09 19:49:00
【问题描述】：

我正在为 Clojurescript webapp 生成 Codox 文档。这是我将用来演示我的问题的示例函数：

(defn breadcrumbs
  "Render Breadcrumbs"
  [app owner]
  (om/component
    (let [crumbs (:breadcrumbs app)]
      (dom/div #js {:id "breadcrumbs"}
        (when (> (count crumbs) 0)
          (apply dom/ol #js {:className "breadcrumb os-border-default"}  
              (om/build-all breadcrumb crumbs)))))))

问题是使用 om/component 会导致 Codox 为四个额外的“隐藏”函数生成文档（大概这些是可以为组件定义的 IRender、IDidUpdate 等函数……但我不确定）。在文档中，这些函数如下所示：

->t6127 (->t6127 面包屑面包屑 meta6128)

->t6130 (->t6130 面包屑面包屑 meta6131)

->t6133 (->t6133 所有者应用程序面包屑 meta6134)

->t6136 (->t6136 所有者应用程序面包屑 meta6137)

这些不需要的文档极大地混淆了最终产品。我知道可以通过“^:no-doc”跳过个别功能，但似乎没有办法在这里使用它。

有没有其他人经历过这种情况并且知道如何摆脱混乱？

【问题讨论】：

标签： clojure documentation clojurescript

【解决方案1】：

Codox 目前在 ClojureScript 中的 reify 存在问题，om/component 在内部使用。

David Nolen 建议区分这些临时值的信息应该可以通过分析器在当前版本的 ClojureScript 中获得，但我无法找到它，也没有人能够指出它。有关更多信息，请参阅 Codox 项目页面上的问题 #72。

【讨论】：

此问题现已在 Codox 0.8.11 中得到修复。

【解决方案2】：

om/component 是一个非常简单的macro，它只为IRender 生成render。看起来 Codox 为 breadcumb（前两个）和 breadcumbs 提供了两个函数。一个可能是您想要的，另一个来自render。您可以像这样编写组件：

(defn breadcrumbs
  "Render Breadcrumbs"
  [app owner]
  (reify
    om/IRender
    (render ^:no-doc [_]
      (let [crumbs (:breadcrumbs app)]
        (dom/div #js {:id "breadcrumbs"}
          (when (> (count crumbs) 0)
            (apply dom/ol #js {:className "breadcrumb os-border-    default"}  
                (om/build-all breadcrumb crumbs)))))))

或编写自己的no-doc-component 宏：

(defmacro no-doc-component
  [& body]
  `(reify
     om.core/IRender
     (~(vary-meta 'render assoc :no-doc true) [this#]
       ~@body)))

免责声明：虽然我已经尝试过宏，但我没有在 Codox 上尝试过。

【讨论】：

谢谢。这听起来像它会工作，但我试过了，它没有。面包屑函数实际上在 Codox 中生成了 3 个函数。一个是正确的，另外两个是我上面贴的垃圾“->t6133”和“->t6136”。
好的。经过一番挖掘，我找到了this。这似乎是 Codox 和 reify 之间的一个已知问题。

【解决方案3】：

weevejester 在 0.8.11 版本中修复了这个问题。

他还将 ClojureScript 分析器配置为不分析依赖项，这允许我为我的 Om 项目生成文档。它还应该减少 :exclude 配置中命名空间的数量。我的已经减到0了。

【讨论】：