[PATCH v2 00/20] [Outreachy] Move doc to header files
- From
Heba Waly via GitGitGadget <gitgitgadget@gmail.com>
- Date
- Nov 6, 2019, 09:59 UTC
- Message-ID
- <pull.434.v2.git.1573034387.gitgitgadget@gmail.com>
- In-Reply-To
- <pull.434.git.1572343246.gitgitgadget@gmail.com>
Move the documentation from Documentation/technical/api-*.txt to the corresponding header file, as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file.
Also documentation/technical/api-*.txt is removed because the information it has is will be redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header files.
api-trace2.txt is not removed because it has lots of valuable information that seems more appropriate to be in a separate doc file not in the trace2.h although the functions documentation is moved to the trace2.h
api-error-handling.txt is not removed as well because no other file seemed to be more suitable for the doc it contains. I'm open to suggestions though.
The ll-merge related doc was removed from api-merge.txt to ll-merge.h, while the rest of the file is left as is.
Signed-off-by: Heba Waly heba.waly@gmail.com
Heba Waly (20): diff: move doc to diff.h and diffcore.h dir: move doc to dir.h graph: move doc to graph.h and graph.c merge: move doc to ll-merge.h sha1-array: move doc to sha1-array.h remote: move doc to remote.h and refspec.h refs: move doc to refs.h attr: move doc to attr.h revision: move doc to revision.h pathspec: move doc to pathspec.h sigchain: move doc to sigchain.h cache: move doc to cache.h argv-array: move doc to argv-array.h credential: move doc to credential.h parse-options: move doc to parse-options.h run-command: move doc to run-command.h trace: move doc to trace.h tree-walk: move doc to tree-walk.h submodule-config: move doc to submodule-config.h trace2: move doc to trace2.h
Documentation/MyFirstContribution.txt | 2 +- Documentation/git-credential.txt | 3 +- Documentation/gitcredentials.txt | 3 +- .../technical/api-allocation-growing.txt | 39 --- Documentation/technical/api-argv-array.txt | 65 ---- Documentation/technical/api-credentials.txt | 271 --------------- Documentation/technical/api-diff.txt | 174 --------- .../technical/api-directory-listing.txt | 130 ------- Documentation/technical/api-gitattributes.txt | 154 -------- Documentation/technical/api-history-graph.txt | 173 --------- Documentation/technical/api-merge.txt | 72 +--- Documentation/technical/api-oid-array.txt | 90 ----- Documentation/technical/api-parse-options.txt | 313 ----------------- Documentation/technical/api-ref-iteration.txt | 78 ----- Documentation/technical/api-remote.txt | 127 ------- .../technical/api-revision-walking.txt | 72 ---- Documentation/technical/api-run-command.txt | 264 -------------- Documentation/technical/api-setup.txt | 47 --- Documentation/technical/api-sigchain.txt | 41 --- .../technical/api-submodule-config.txt | 66 ---- Documentation/technical/api-trace.txt | 140 -------- Documentation/technical/api-trace2.txt | 262 +------------- Documentation/technical/api-tree-walking.txt | 149 -------- argv-array.h | 62 ++++ attr.h | 141 +++++++- cache.h | 41 ++- credential.h | 236 +++++++++++++ diff.h | 127 +++++++ diffcore.h | 32 ++ dir.h | 118 ++++++- graph.c | 1 + graph.h | 121 +++++++ ll-merge.h | 73 +++- parse-options.h | 329 ++++++++++++++++++ pathspec.h | 34 +- refs.h | 51 +++ refspec.h | 16 + remote.h | 57 ++- revision.h | 59 ++++ run-command.h | 254 +++++++++++++- sha1-array.h | 80 +++++ sigchain.h | 42 +++ submodule-config.h | 38 +- trace.h | 133 ++++++- trace2.h | 146 ++++++-- tree-walk.h | 122 ++++++- 46 files changed, 2263 insertions(+), 2785 deletions(-) delete mode 100644 Documentation/technical/api-allocation-growing.txt delete mode 100644 Documentation/technical/api-argv-array.txt delete mode 100644 Documentation/technical/api-credentials.txt delete mode 100644 Documentation/technical/api-diff.txt delete mode 100644 Documentation/technical/api-directory-listing.txt delete mode 100644 Documentation/technical/api-gitattributes.txt delete mode 100644 Documentation/technical/api-history-graph.txt delete mode 100644 Documentation/technical/api-oid-array.txt delete mode 100644 Documentation/technical/api-parse-options.txt delete mode 100644 Documentation/technical/api-ref-iteration.txt delete mode 100644 Documentation/technical/api-remote.txt delete mode 100644 Documentation/technical/api-revision-walking.txt delete mode 100644 Documentation/technical/api-run-command.txt delete mode 100644 Documentation/technical/api-setup.txt delete mode 100644 Documentation/technical/api-sigchain.txt delete mode 100644 Documentation/technical/api-submodule-config.txt delete mode 100644 Documentation/technical/api-trace.txt delete mode 100644 Documentation/technical/api-tree-walking.txt
base-commit: da72936f544fec5a335e66432610e4cef4430991 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-434%2FHebaWaly%2Fmove-doc-to-header-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-434/HebaWaly/move-doc-to-header-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/434
Range-diff vs v1:
1: 1796c119be = 1: 6cd5f75315 diff: move doc to diff.h and diffcore.h
2: 290935e846 = 2: cdb32c159a dir: move doc to dir.h
3: dabfe5e60b = 3: fd89383a46 graph: move doc to graph.h and graph.c
4: 504f1f7c89 ! 4: a70ed4b79b merge: move doc to ll-merge.h
@@ -2,51 +2,24 @@
merge: move doc to ll-merge.h
- Move the documentation from Documentation/technical/api-merge.txt to
- ll-merge.h as it's easier for the developers to find the usage
+ Move the related documentation from Documentation/technical/api-merge.txt
+ to ll-merge.h as it's easier for the developers to find the usage
information beside the code instead of looking for it in another doc file.
- Also documentation/technical/api-merge.txt is removed because the
- information it has is now redundant and it'll be hard to keep it up to
- date and synchronized with the documentation in the header file.
+ Only the ll-merge related doc is removed from
+ documentation/technical/api-merge.txt because this information will be
+ redundant and it'll be hard to keep it up to date and synchronized with
+ the documentation in ll-merge.h.
Signed-off-by: Heba Waly <heba.waly@gmail.com>
diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt
- deleted file mode 100644
--- a/Documentation/technical/api-merge.txt
- +++ /dev/null
+ +++ b/Documentation/technical/api-merge.txt
@@
--merge API
--=========
--
--The merge API helps a program to reconcile two competing sets of
--improvements to some files (e.g., unregistered changes from the work
--tree versus changes involved in switching to a new branch), reporting
--conflicts if found. The library called through this API is
--responsible for a few things.
--
-- * determining which trees to merge (recursive ancestor consolidation);
--
-- * lining up corresponding files in the trees to be merged (rename
-- detection, subtree shifting), reporting edge cases like add/add
-- and rename/rename conflicts to the user;
--
-- * performing a three-way merge of corresponding files, taking
-- path-specific merge drivers (specified in `.gitattributes`)
-- into account.
--
--Data structures
-----------------
--
--* `mmbuffer_t`, `mmfile_t`
--
--These store data usable for use by the xdiff backend, for writing and
--for reading, respectively. See `xdiff/xdiff.h` for the definitions
--and `diff.c` for examples.
--
--* `struct ll_merge_options`
--
+
+ * `struct ll_merge_options`
+
-This describes the set of options the calling program wants to affect
-the operation of a low-level (single file) merge. Some options:
-
@@ -69,10 +42,11 @@
- before merging. Use this when the merge is likely to have
- overlapped with a change in smudge/clean or end-of-line
- normalization rules.
--
--Low-level (single file) merge
-------------------------------
--
++Check ll-merge.h for details.
+
+ Low-level (single file) merge
+ -----------------------------
+
-`ll_merge`::
-
- Perform a three-way single-file merge in core. This is
@@ -121,6 +95,7 @@
- - merge options
-
-(Daniel, Miklos, Stephan, JC)
++Check ll-merge.h for details.
diff --git a/ll-merge.h b/ll-merge.h
--- a/ll-merge.h
@@ -130,21 +105,6 @@
#include "xdiff/xdiff.h"
+/**
-+ * The merge API helps a program to reconcile two competing sets of
-+ * improvements to some files (e.g., unregistered changes from the work
-+ * tree versus changes involved in switching to a new branch), reporting
-+ * conflicts if found. The library called through this API is
-+ * responsible for a few things.
-+ *
-+ * - determining which trees to merge (recursive ancestor consolidation);
-+ *
-+ * - lining up corresponding files in the trees to be merged (rename
-+ * detection, subtree shifting), reporting edge cases like add/add
-+ * and rename/rename conflicts to the user;
-+ *
-+ * - performing a three-way merge of corresponding files, taking
-+ * path-specific merge drivers (specified in `.gitattributes`)
-+ * into account.
+ *
+ * Calling sequence:
+ * ----------------
@@ -187,8 +147,10 @@
+
+ /**
+ * Behave as though this were part of a merge between common ancestors in
-+ * a recursive merge. If a helper program is specified by the
-+ * `[merge "<driver>"] recursive` configuration, it will be used.
++ * a recursive merge (merges of binary files may need to be handled
++ * differently in such cases, for example). If a helper program is
++ * specified by the `[merge "<driver>"] recursive` configuration, it will
++ * be used.
+ */
unsigned virtual_ancestor : 1;
- unsigned variant : 2; /* favor ours, favor theirs, or union merge */
@@ -208,7 +170,13 @@
+ */
unsigned renormalize : 1;
+
++ /**
++ * Increase the length of conflict markers so that nested conflicts
++ * can be differentiated.
++ */
unsigned extra_marker_size;
++
++ /* Extra xpparam_t flags as defined in xdiff/xdiff.h. */
long xdl_opts;
};
5: 4302bdd13f = 5: fc81758644 sha1-array: move doc to sha1-array.h
6: e16f5b25e9 = 6: eb7adbcbcc remote: move doc to remote.h and refspec.h
7: 9c900c58a2 = 7: 24d0765df9 refs: move doc to refs.h
8: 052d4e5e56 = 8: 4ea49f76c7 attr: move doc to attr.h
9: afab6d5f4e = 9: acd6287ced revision: move doc to revision.h
10: 5757216949 = 10: dcb78b6708 pathspec: move doc to pathspec.h
-: ---------- > 11: 3499b99538 sigchain: move doc to sigchain.h
-: ---------- > 12: a280cf7f90 cache: move doc to cache.h
-: ---------- > 13: 314864e42c argv-array: move doc to argv-array.h
-: ---------- > 14: 8fd1fa98a8 credential: move doc to credential.h
-: ---------- > 15: 3d1e7e72ef parse-options: move doc to parse-options.h
-: ---------- > 16: 5d93cab5d9 run-command: move doc to run-command.h
-: ---------- > 17: 9b02b44cc8 trace: move doc to trace.h
-: ---------- > 18: 9c8f5c1cbe tree-walk: move doc to tree-walk.h
-: ---------- > 19: 7fa5cdf83f submodule-config: move doc to submodule-config.h
-: ---------- > 20: 4c3215e92b trace2: move doc to trace2.h-- gitgitgadget