kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity
git/Documentation
History
Jeff King bdfdaa4978 strbuf.h: integrate api-strbuf.txt documentation 
Some of strbuf is documented as comments above functions,
and some is separate in Documentation/technical/api-strbuf.txt.
This makes it annoying to find the appropriate documentation.
We'd rather have it all in one place, which means all in the
text document, or all in the header.

Let's choose the header as that place. Even though the
formatting is not quite as pretty, this keeps the
documentation close to the related code.  The hope is that
this makes it easier to find what you want (human-readable
comments are right next to the C declarations), and easier
for writers to keep the documentation up to date.

This is more or less a straight import of the text from
api-strbuf.txt into C comments, complete with asciidoc
formatting. The exceptions are:

 1. All comments created in this way are started with "/**"
    to indicate they are part of the API documentation. This
    may help later with extracting the text to pretty-print
    it.

 2. Function descriptions do not repeat the function name,
    as it is available in the context directly below.  So:

      `strbuf_add`::

          Add data of given length to the buffer.

    from api-strbuf.txt becomes:

      /**
       * Add data of given length to the buffer.
       */
      void strbuf_add(struct strbuf *sb, const void *, size_t);

    As a result, any block-continuation required in asciidoc
    for that list item was dropped in favor of straight
    blank-line paragraph (since it is not necessary when we
    are not in a list item).

 3. There is minor re-wording to integrate existing comments
    and api-strbuf text. In each case, I took whichever
    version was more descriptive, and eliminated any
    redundancies. In one case, for strbuf_addstr, the api
    documentation gave its inline definition; I eliminated
    this as redundant with the actual definition, which can
    be seen directly below the comment.

 4. The functions in the header file are re-ordered to match
    the ordering of the API documentation, under the
    assumption that more thought went into the grouping
    there.

Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
 		2015-01-16 14:40:46 -08:00
..
RelNotes Second batch for 2.3 cycle 2014-12-12 14:37:33 -08:00
howto Documentation: typofixes 2014-11-04 13:14:44 -08:00
technical strbuf.h: integrate api-strbuf.txt documentation 2015-01-16 14:40:46 -08:00
.gitattributes
…
.gitignore
…
CodingGuidelines Merge branch 'po/error-message-style' 2014-07-16 11:33:03 -07:00
Makefile Merge branch 'bc/asciidoctor' 2014-10-29 10:07:40 -07:00
SubmittingPatches SubmittingPatches: final submission is To: maintainer and CC: list 2014-11-13 10:39:24 -08:00
asciidoc.conf
…
blame-options.txt blame: document multiple -L support 2013-08-06 14:34:43 -07:00
build-docdep.perl
…
cat-texi.perl
…
cmd-list.perl
…
config.txt Merge branch 'jk/colors-fix' 2014-12-12 14:31:39 -08:00
date-formats.txt Correct word usage of "timezone" in "Documentation" directory 2013-11-12 10:47:17 -08:00
diff-config.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
diff-format.txt
…
diff-generate-patch.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
diff-options.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
docbook-xsl.css
…
docbook.xsl
…
everyday.txto doc: add 'everyday' to 'git help' 2014-10-10 16:02:26 -07:00
fetch-options.txt fetch: allow explicit --refmap to override configuration 2014-06-05 15:13:12 -07:00
fix-texi.perl
…
git-add.txt Merge branch 'jl/nor-or-nand-and' 2014-04-08 12:00:28 -07:00
git-am.txt Merge branch 'cp/am-patch-format-doc' 2014-03-25 11:01:31 -07:00
git-annotate.txt
…
git-apply.txt
…
git-archimport.txt
…
git-archive.txt docs: clarify remote restrictions for git-upload-archive 2014-02-28 09:55:35 -08:00
git-bisect-lk2009.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-bisect.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
git-blame.txt docs/git-blame: explain more clearly the example pickaxe use 2014-02-11 11:03:07 -08:00
git-branch.txt Refer to branch.<name>.remote/merge when documenting --track 2013-09-09 11:03:01 -07:00
git-bundle.txt
…
git-cat-file.txt cat-file: provide %(deltabase) batch format 2013-12-26 11:54:26 -08:00
git-check-attr.txt Merge branch 'jc/check-x-z' 2013-09-04 12:23:25 -07:00
git-check-ignore.txt check-ignore: Add option to ignore index contents 2013-09-12 15:40:29 -07:00
git-check-mailmap.txt
…
git-check-ref-format.txt Add new @ shortcut for HEAD 2013-09-12 14:39:34 -07:00
git-checkout-index.txt
…
git-checkout.txt Documentation: @{-N} can refer to a commit 2014-01-21 13:50:00 -08:00
git-cherry-pick.txt parse-options: multi-word argh should use dash to separate words 2014-03-24 10:43:34 -07:00
git-cherry.txt Documentation: revamp git-cherry(1) 2013-11-27 12:16:49 -08:00
git-citool.txt
…
git-clean.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-clone.txt docs/git-clone: clarify use of --no-hardlinks option 2014-02-11 11:03:07 -08:00
git-column.txt doc: remote author/documentation sections from more pages 2014-01-27 08:34:34 -08:00
git-commit-tree.txt commit-tree: add and document --no-gpg-sign 2014-02-24 14:51:35 -08:00
git-commit.txt Merge branch 'jc/doc-commit-only' 2014-11-18 10:19:42 -08:00
git-config.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
git-count-objects.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
git-credential-cache--daemon.txt credential-cache: close stderr in daemon process 2014-09-16 11:11:58 -07:00
git-credential-cache.txt
…
git-credential-store.txt docs/credential-store: s/--store/--file/ 2014-11-06 09:51:08 -08:00
git-credential.txt Documentation: make AsciiDoc links always point to HTML files 2013-09-06 14:49:06 -07:00
git-cvsexportcommit.txt
…
git-cvsimport.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-cvsserver.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-daemon.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
git-describe.txt use 'commit-ish' instead of 'committish' 2013-09-04 15:03:03 -07:00
git-diff-files.txt
…
git-diff-index.txt
…
git-diff-tree.txt
…
git-diff.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
git-difftool.txt difftool: add support for --trust-exit-code 2014-10-28 10:36:57 -07:00
git-fast-export.txt Merge branch 'mh/doc-remote-helper-xref' 2014-11-19 13:47:56 -08:00
git-fast-import.txt doc: add some crossrefs between manual pages 2014-11-11 14:47:04 -08:00
git-fetch-pack.txt Merge branch 'tb/doc-fetch-pack-url' into maint 2013-12-17 11:34:24 -08:00
git-fetch.txt docs: Explain the purpose of fetch's and pull's <refspec> parameter. 2014-06-12 09:59:13 -07:00
git-filter-branch.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-fmt-merge-msg.txt
…
git-for-each-ref.txt doc: remote author/documentation sections from more pages 2014-01-27 08:34:34 -08:00
git-format-patch.txt format-patch: add "--signature-file=<file>" option 2014-05-27 12:38:32 -07:00
git-fsck-objects.txt
…
git-fsck.txt
…
git-gc.txt gc --aggressive: make --depth configurable 2014-03-31 10:26:24 -07:00
git-get-tar-commit-id.txt
…
git-grep.txt grep: add grep.fullName config variable 2014-03-20 12:38:00 -07:00
git-gui.txt
…
git-hash-object.txt
…
git-help.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
git-http-backend.txt Merge commit 'doc/http-backend: missing accent grave in literal mark-up' 2014-04-09 11:45:04 -07:00
git-http-fetch.txt
…
git-http-push.txt
…
git-imap-send.txt Documentation: fix mismatched delimiters in git-imap-send 2014-10-13 13:35:37 -07:00
git-index-pack.txt
…
git-init-db.txt
…
git-init.txt Documentation: git-init: flesh out example 2014-08-08 13:17:42 -07:00
git-instaweb.txt
…
git-interpret-trailers.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-log.txt Merge branch 'jj/log-doc' into maint 2013-12-17 11:35:41 -08:00
git-ls-files.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
git-ls-remote.txt
…
git-ls-tree.txt
…
git-mailinfo.txt
…
git-mailsplit.txt
…
git-merge-base.txt merge-base: teach "--fork-point" mode 2013-10-29 13:06:08 -07:00
git-merge-file.txt Documentation/git-merge-file: document option "--diff3" 2013-08-09 14:19:59 -07:00
git-merge-index.txt
…
git-merge-one-file.txt
…
git-merge-tree.txt use 'tree-ish' instead of 'treeish' 2013-09-04 15:02:56 -07:00
git-merge.txt merge: enable defaulttoupstream by default 2014-04-22 12:53:59 -07:00
git-mergetool--lib.txt
…
git-mergetool.txt mergetool: document the default for --[no-]prompt 2014-04-24 11:29:05 -07:00
git-mktag.txt
…
git-mktree.txt
…
git-mv.txt mv: better document side effects when moving a submodule 2014-01-07 14:33:04 -08:00
git-name-rev.txt use 'commit-ish' instead of 'committish' 2013-09-04 15:03:03 -07:00
git-notes.txt builtin/notes: add --allow-empty, to allow storing empty notes 2014-11-12 11:00:11 -08:00
git-p4.txt git p4 doc: use two-line style for options with multiple spellings 2014-01-22 08:06:20 -08:00
git-pack-objects.txt upload-pack: send shallow info over stdin to pack-objects 2014-03-11 13:32:10 -07:00
git-pack-redundant.txt
…
git-pack-refs.txt
…
git-parse-remote.txt
…
git-patch-id.txt patch-id: make it stable against hunk reordering 2014-06-10 13:09:24 -07:00
git-prune-packed.txt Documentation: adjust document title underlining 2014-10-13 13:35:18 -07:00
git-prune.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
git-pull.txt Merge branch 'jc/maint-pull-docfix' into maint 2014-02-05 14:03:47 -08:00
git-push.txt Merge branch 'po/everyday-doc' 2014-12-12 14:31:34 -08:00
git-quiltimport.txt Documentation: adjust document title underlining 2014-10-13 13:35:18 -07:00
git-read-tree.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
git-rebase.txt Merge branch 'so/rebase-doc-fork-point' 2014-10-14 10:49:07 -07:00
git-receive-pack.txt signed push: allow stale nonce in stateless mode 2014-09-17 15:19:54 -07:00
git-reflog.txt
…
git-relink.txt
…
git-remote-ext.txt doc: add some crossrefs between manual pages 2014-11-11 14:47:04 -08:00
git-remote-fd.txt doc: add some crossrefs between manual pages 2014-11-11 14:47:04 -08:00
git-remote-helpers.txto
…
git-remote-testgit.txt
…
git-remote.txt docs/git-remote: capitalize first word of initial blurb 2014-02-11 11:03:07 -08:00
git-repack.txt Merge branch 'jk/repack-pack-keep-objects' 2014-03-18 13:50:29 -07:00
git-replace.txt Merge branch 'cc/replace-graft' 2014-07-27 15:14:18 -07:00
git-request-pull.txt request-pull: documentation updates 2014-03-13 14:22:20 -07:00
git-rerere.txt
…
git-reset.txt Merge branch 'jl/nor-or-nand-and' 2014-04-08 12:00:28 -07:00
git-rev-list.txt pretty: provide a strict ISO 8601 date format 2014-08-29 12:37:02 -07:00
git-rev-parse.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-revert.txt parse-options: multi-word argh should use dash to separate words 2014-03-24 10:43:34 -07:00
git-rm.txt rm: better document side effects when removing a submodule 2014-01-07 14:34:06 -08:00
git-send-email.txt Merge branch 'mt/send-email-cover-to-cc' 2014-06-20 13:12:20 -07:00
git-send-pack.txt send-pack: take refspecs over stdin 2014-08-26 12:58:02 -07:00
git-sh-i18n--envsubst.txt
…
git-sh-i18n.txt
…
git-sh-setup.txt Merge branch 'jc/reflog-doc' 2013-10-18 13:50:12 -07:00
git-shell.txt shell doc: remove stray "+" in example 2014-05-08 10:26:26 -07:00
git-shortlog.txt
…
git-show-branch.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
git-show-index.txt
…
git-show-ref.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
git-show.txt
…
git-stage.txt Documentation: adjust document title underlining 2014-10-13 13:35:18 -07:00
git-stash.txt stash doc: mention short form -k in save description 2014-02-24 09:13:30 -08:00
git-status.txt doc: fix 'git status --help' character quoting 2014-10-19 20:45:16 -07:00
git-stripspace.txt
…
git-submodule.txt Merge branch 'mc/doc-submodule-sync-recurse' into maint 2014-07-10 11:08:31 -07:00
git-svn.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-symbolic-ref.txt
…
git-tag.txt Merge branch 'maint-2.0' into maint 2014-10-07 13:40:51 -07:00
git-tools.txt
…
git-unpack-file.txt
…
git-unpack-objects.txt Merge branch 'vd/doc-unpack-objects' into maint 2013-11-07 14:37:36 -08:00
git-update-index.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
git-update-ref.txt update-ref --stdin -z: deprecate interpreting the empty string as zeros 2014-04-07 12:09:13 -07:00
git-update-server-info.txt
…
git-upload-archive.txt add uploadarchive.allowUnreachable option 2014-02-28 09:55:37 -08:00
git-upload-pack.txt
…
git-var.txt
…
git-verify-commit.txt verify-commit: scriptable commit signature verification 2014-06-23 15:50:31 -07:00
git-verify-pack.txt
…
git-verify-tag.txt
…
git-web--browse.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
git-whatchanged.txt whatchanged: document its historical nature 2013-08-13 09:01:54 -07:00
git-write-tree.txt
…
git.txt Merge branch 'tq/git-ssh-command' 2014-12-05 11:39:25 -08:00
gitattributes.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
gitcli.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
gitcore-tutorial.txt doc: add 'everyday' to 'git help' 2014-10-10 16:02:26 -07:00
gitcredentials.txt
…
gitcvs-migration.txt doc: add 'everyday' to 'git help' 2014-10-10 16:02:26 -07:00
gitdiffcore.txt
…
giteveryday.txt doc: add 'everyday' to 'git help' 2014-10-10 16:02:26 -07:00
gitglossary.txt doc: add 'everyday' to 'git help' 2014-10-10 16:02:26 -07:00
githooks.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
gitignore.txt Merge branch 'nd/gitignore-trailing-whitespace' into maint 2014-11-12 12:13:12 -08:00
gitk.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
gitmodules.txt status/commit: show staged submodules regardless of ignore config 2014-04-07 10:32:20 -07:00
gitnamespaces.txt
…
gitremote-helpers.txt doc: add some crossrefs between manual pages 2014-11-11 14:47:04 -08:00
gitrepository-layout.txt read-cache: split-index mode 2014-06-13 11:49:39 -07:00
gitrevisions.txt
…
gittutorial-2.txt Merge branch 'sn/tutorial-status-output-example' 2014-11-19 13:47:59 -08:00
gittutorial.txt Merge branch 'sn/tutorial-status-output-example' 2014-11-19 13:47:59 -08:00
gitweb.conf.txt Documentation: use "command-line" when used as a compound adjective, and fix other minor grammatical issues 2014-05-21 13:57:10 -07:00
gitweb.txt Documentation: fix documentation AsciiDoc links for external urls 2014-02-20 14:14:58 -08:00
gitworkflows.txt
…
glossary-content.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
howto-index.sh howto-index.sh: use the $( ... ) construct for command substitution 2014-04-17 11:14:57 -07:00
i18n.txt
…
install-doc-quick.sh
…
install-webdoc.sh install-webdoc.sh: use the $( ... ) construct for command substitution 2014-04-17 11:14:58 -07:00
line-range-format.txt line-range: teach -L^:RE to search from start of file 2013-08-06 14:48:02 -07:00
mailmap.txt
…
manpage-1.72.xsl
…
manpage-base-url.xsl.in
…
manpage-base.xsl
…
manpage-bold-literal.xsl
…
manpage-normal.xsl
…
manpage-quote-apos.xsl
…
manpage-suppress-sp.xsl
…
merge-config.txt
…
merge-options.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
merge-strategies.txt Merge branch 'rr/doc-merge-strategies' into maint 2014-04-03 13:39:03 -07:00
pretty-formats.txt Merge branch 'bc/asciidoc-pretty-formats-fix' into maint 2014-10-29 10:35:10 -07:00
pretty-options.txt Documentation: fix misuses of "nor" 2014-03-31 15:16:22 -07:00
pull-fetch-param.txt docs: Explain the purpose of fetch's and pull's <refspec> parameter. 2014-06-12 09:59:13 -07:00
rev-list-options.txt Documentation: typofixes 2014-11-04 13:14:44 -08:00
revisions.txt Documentation: mention config sources for @{upstream} 2014-05-13 12:35:00 -07:00
sequencer.txt
…
urls-remotes.txt
…
urls.txt
…
user-manual.conf
…
user-manual.txt Merge branch 'jm/doc-wording-tweaks' 2014-06-16 12:18:39 -07:00