Modularize and document public API (#1449)

Summary:
X-link: facebook/react-native#41317

Pull Request resolved: #1449

This aims to clean up the public Yoga C API, by:
1. Documenting public YGNode, YGValue, YGConfig APIs
2. Splitting APIs for specific objects into different header files (because Yoga.h was big enough without documentation)
3. Reordering headers and definitions for consistent grouping

Changelog: [Internal]

Reviewed By: joevilches

Differential Revision: D50963424

fbshipit-source-id: 45124b7370256fc63aefd6d5b7641466e9a79d3b

yoga/YGConfig.cpp

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#include <yoga/Yoga.h>
+#include <yoga/debug/AssertFatal.h>
+#include <yoga/debug/Log.h>
+
+using namespace facebook;
+using namespace facebook::yoga;
+
+YGConfigRef YGConfigNew(void) {
+  return new yoga::Config(getDefaultLogger());
+}
+
+void YGConfigFree(const YGConfigRef config) {
+  delete resolveRef(config);
+}
+
+YGConfigConstRef YGConfigGetDefault() {
+  return &yoga::Config::getDefault();
+}
+
+void YGConfigSetUseWebDefaults(const YGConfigRef config, const bool enabled) {
+  resolveRef(config)->setUseWebDefaults(enabled);
+}
+
+bool YGConfigGetUseWebDefaults(const YGConfigConstRef config) {
+  return resolveRef(config)->useWebDefaults();
+}
+
+void YGConfigSetPointScaleFactor(
+    const YGConfigRef config,
+    const float pixelsInPoint) {
+  yoga::assertFatalWithConfig(
+      resolveRef(config),
+      pixelsInPoint >= 0.0f,
+      "Scale factor should not be less than zero");
+
+  // We store points for Pixel as we will use it for rounding
+  if (pixelsInPoint == 0.0f) {
+    // Zero is used to skip rounding
+    resolveRef(config)->setPointScaleFactor(0.0f);
+  } else {
+    resolveRef(config)->setPointScaleFactor(pixelsInPoint);
+  }
+}
+
+float YGConfigGetPointScaleFactor(const YGConfigConstRef config) {
+  return resolveRef(config)->getPointScaleFactor();
+}
+
+void YGConfigSetErrata(YGConfigRef config, YGErrata errata) {
+  resolveRef(config)->setErrata(scopedEnum(errata));
+}
+
+YGErrata YGConfigGetErrata(YGConfigConstRef config) {
+  return unscopedEnum(resolveRef(config)->getErrata());
+}
+
+void YGConfigSetLogger(const YGConfigRef config, YGLogger logger) {
+  if (logger != nullptr) {
+    resolveRef(config)->setLogger(logger);
+  } else {
+    resolveRef(config)->setLogger(getDefaultLogger());
+  }
+}
+
+void YGConfigSetContext(const YGConfigRef config, void* context) {
+  resolveRef(config)->setContext(context);
+}
+
+void* YGConfigGetContext(const YGConfigConstRef config) {
+  return resolveRef(config)->getContext();
+}
+
+void YGConfigSetExperimentalFeatureEnabled(
+    const YGConfigRef config,
+    const YGExperimentalFeature feature,
+    const bool enabled) {
+  resolveRef(config)->setExperimentalFeatureEnabled(
+      scopedEnum(feature), enabled);
+}
+
+bool YGConfigIsExperimentalFeatureEnabled(
+    const YGConfigConstRef config,
+    const YGExperimentalFeature feature) {
+  return resolveRef(config)->isExperimentalFeatureEnabled(scopedEnum(feature));
+}
+
+void YGConfigSetCloneNodeFunc(
+    const YGConfigRef config,
+    const YGCloneNodeFunc callback) {
+  resolveRef(config)->setCloneNodeCallback(callback);
+}
+
+void YGConfigSetPrintTreeFlag(YGConfigRef config, bool enabled) {
+  resolveRef(config)->setShouldPrintTree(enabled);
+}

yoga/YGConfig.h

@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stddef.h>
+
+#include <yoga/YGEnums.h>
+#include <yoga/YGMacros.h>
+
+YG_EXTERN_C_BEGIN
+
+typedef struct YGNode* YGNodeRef;
+typedef const struct YGNode* YGNodeConstRef;
+
+/**
+ * Handle to a mutable Yoga configuration.
+ */
+typedef struct YGConfig* YGConfigRef;
+
+/**
+ * Handle to an immutable Yoga configruation.
+ */
+typedef const struct YGConfig* YGConfigConstRef;
+
+/**
+ * Allocates a set of configuration options. The configuration may be applied to
+ * multiple nodes (i.e. a single global config), or can be applied more
+ * granularly per-node.
+ */
+YG_EXPORT YGConfigRef YGConfigNew(void);
+
+/**
+ * Frees the associated Yoga configuration.
+ */
+YG_EXPORT void YGConfigFree(YGConfigRef config);
+
+/**
+ * Returns the default config values set by Yoga.
+ */
+YG_EXPORT YGConfigConstRef YGConfigGetDefault(void);
+
+/**
+ * Yoga by default creates new nodes with style defaults different from flexbox
+ * on web (e.g. `YGFlexDirectionColumn` and `YGPositionRelative`).
+ * `UseWebDefaults` instructs Yoga to instead use a default style consistent
+ * with the web.
+ */
+YG_EXPORT void YGConfigSetUseWebDefaults(YGConfigRef config, bool enabled);
+
+/**
+ * Whether the configuration is set to use web defaults.
+ */
+YG_EXPORT bool YGConfigGetUseWebDefaults(YGConfigConstRef config);
+
+/**
+ * Yoga will by deafult round final layout positions and dimensions to the
+ * nearst point. `pointScaleFactor` controls the density of the grid used for
+ * layout rounding (e.g. to round to the closest display pixel).
+ *
+ * May be set to 0.0f to avoid rounding the layout results.
+ */
+YG_EXPORT void YGConfigSetPointScaleFactor(
+    YGConfigRef config,
+    float pixelsInPoint);
+
+/**
+ * Get the currently set point scale factor.
+ */
+YG_EXPORT float YGConfigGetPointScaleFactor(YGConfigConstRef config);
+
+/**
+ * Configures how Yoga balances W3C conformance vs compatibility with layouts
+ * created against earlier versions of Yoga.
+ *
+ * By deafult Yoga will prioritize W3C conformance. `Errata` may be set to ask
+ * Yoga to produce specific incorrect behaviors. E.g. `YGConfigSetErrata(config,
+ * YGErrataPositionStaticBehavesLikeRelative)`.
+ *
+ * YGErrata is a bitmask, and multiple errata may be set at once. Predfined
+ * constants exist for convenience:
+ * 1. YGErrataNone: No errata
+ * 2. YGErrataClassic: Match layout behaviors of Yoga 1.x
+ * 3. YGErrataAll: Match layout behaviors of Yoga 1.x, including
+ * `UseLegacyStretchBehaviour`
+ */
+YG_EXPORT void YGConfigSetErrata(YGConfigRef config, YGErrata errata);
+
+/**
+ * Get the currently set errata.
+ */
+YG_EXPORT YGErrata YGConfigGetErrata(YGConfigConstRef config);
+
+/**
+ * Function pointer type for YGConfigSetLogger.
+ */
+typedef int (*YGLogger)(
+    YGConfigConstRef config,
+    YGNodeConstRef node,
+    YGLogLevel level,
+    const char* format,
+    va_list args);
+
+/**
+ * Set a custom log function for to use when logging diagnostics or fatal.
+ * errors.
+ */
+YG_EXPORT void YGConfigSetLogger(YGConfigRef config, YGLogger logger);
+
+/**
+ * Sets an arbitrary context pointer on the config which may be read from during
+ * callbacks.
+ */
+YG_EXPORT void YGConfigSetContext(YGConfigRef config, void* context);
+
+/**
+ * Gets the currently set context.
+ */
+YG_EXPORT void* YGConfigGetContext(YGConfigConstRef config);
+
+/**
+ * Function pointer type for YGConfigSetCloneNodeFunc.
+ */
+typedef YGNodeRef (*YGCloneNodeFunc)(
+    YGNodeConstRef oldNode,
+    YGNodeConstRef owner,
+    size_t childIndex);
+
+/**
+ * Enable an experimental/unsupported feature in Yoga.
+ */
+YG_EXPORT void YGConfigSetExperimentalFeatureEnabled(
+    YGConfigRef config,
+    YGExperimentalFeature feature,
+    bool enabled);
+
+/**
+ * Whether an experimental feature is set.
+ */
+YG_EXPORT bool YGConfigIsExperimentalFeatureEnabled(
+    YGConfigConstRef config,
+    YGExperimentalFeature feature);
+
+/**
+ * Sets a callback, called during layout, to create a new mutable Yoga node if
+ * Yoga must write to it and its owner is not its parent observed during layout.
+ */
+YG_EXPORT void YGConfigSetCloneNodeFunc(
+    YGConfigRef config,
+    YGCloneNodeFunc callback);
+
+/**
+ * Allows printing the Yoga node tree during layout for debugging purposes.
+ */
+YG_EXPORT void YGConfigSetPrintTreeFlag(YGConfigRef config, bool enabled);
+
+YG_EXTERN_C_END