Commit 82abd40d80a8912043dd072a09962f06df193e36
2016-02-07T13:35:16
filter: clean up documentation around custom filters
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
diff --git a/include/git2/sys/filter.h b/include/git2/sys/filter.h
index baf1515..d0e5d4d 100644
--- a/include/git2/sys/filter.h
+++ b/include/git2/sys/filter.h
@@ -127,17 +127,6 @@ GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *sr
*/
GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src);
-/*
- * struct git_filter
- *
- * The filter lifecycle:
- * - initialize - first use of filter
- * - shutdown - filter removed/unregistered from system
- * - check - considering filter for file
- * - apply - apply filter to file contents
- * - cleanup - done with file
- */
-
/**
* Initialize callback on filter
*
@@ -233,31 +222,51 @@ typedef void (*git_filter_cleanup_fn)(
* To associate extra data with a filter, allocate extra data and put the
* `git_filter` struct at the start of your data buffer, then cast the
* `self` pointer to your larger structure when your callback is invoked.
- *
- * `version` should be set to GIT_FILTER_VERSION
- *
- * `attributes` is a whitespace-separated list of attribute names to check
- * for this filter (e.g. "eol crlf text"). If the attribute name is bare,
- * it will be simply loaded and passed to the `check` callback. If it has
- * a value (i.e. "name=value"), the attribute must match that value for
- * the filter to be applied. The value may be a wildcard (eg, "name=*"),
- * in which case the filter will be invoked for any value for the given
- * attribute name. See the attribute parameter of the `check` callback
- * for the attribute value that was specified.
- *
- * The `initialize`, `shutdown`, `check`, `apply`, and `cleanup` callbacks
- * are all documented above with the respective function pointer typedefs.
*/
struct git_filter {
+ /** The `version` field should be set to `GIT_FILTER_VERSION`. */
unsigned int version;
+ /**
+ * A whitespace-separated list of attribute names to check for this
+ * filter (e.g. "eol crlf text"). If the attribute name is bare, it
+ * will be simply loaded and passed to the `check` callback. If it
+ * has a value (i.e. "name=value"), the attribute must match that
+ * value for the filter to be applied. The value may be a wildcard
+ * (eg, "name=*"), in which case the filter will be invoked for any
+ * value for the given attribute name. See the attribute parameter
+ * of the `check` callback for the attribute value that was specified.
+ */
const char *attributes;
+ /** Called when the filter is first used for any file. */
git_filter_init_fn initialize;
+
+ /** Called when the filter is removed or unregistered from the system. */
git_filter_shutdown_fn shutdown;
+
+ /**
+ * Called to determine whether the filter should be invoked for a
+ * given file. If this function returns `GIT_PASSTHROUGH` then the
+ * `apply` function will not be invoked and the contents will be passed
+ * through unmodified.
+ */
git_filter_check_fn check;
+
+ /**
+ * Called to actually apply the filter to file contents. If this
+ * function returns `GIT_PASSTHROUGH` then the contents will be passed
+ * through unmodified.
+ */
git_filter_apply_fn apply;
+
+ /**
+ * Called to apply the filter in a streaming manner. If this is not
+ * specified then the system will call `apply` with the whole buffer.
+ */
git_filter_stream_fn stream;
+
+ /** Called when the system is done filtering for a file. */
git_filter_cleanup_fn cleanup;
};