Fix docurium missing includes #4530

tiennou · 2018-02-12T00:15:24Z

The first commit makes git_oid & git_buf "globally" visible (ie. less likely to be forgotten) by including them from types.h. If that's not really appropriate, it could be fixed more precisely by going through each error from this script.

Apart from a typechange (see worktree: commit), the rest is minor fixups + missing documentation.

Fixes #4213, #4495, maybe #4492.

tiennou · 2018-02-12T20:47:31Z

I've pushed my work-in-progress to my own gh-pages branch so it's available here. Note that it requires tweaks to docurium which aren't upstream (yet, there's some in a PR, but now there's more 😉).

Highlights :

the transaction section makes its first appearance.
I've disabled a check for debugging reasons which makes every valid identifier at least appear (hence the imaxdiv section, which comes from git2/stdint.h, and surely a bunch of others). Still not sure whether we want that or not (the rationale for the change is warnings about undocumented things when docurium-ing)
some types lost their documentation (eg. git_odb_backend). IIUC, it stems from parsing the "quick" comment from git2/types.h before the real struct def in git2/sys/odb_backend.h. Still investigating.

pks-t

Really, thanks a lot for working on this! Documentation is always a very important piece of the puzzle that most developers (including myself) hate working on. Some comments below.

pks-t · 2018-02-16T09:59:13Z

include/git2/attr.h

+ * are multiple rules for a given file. The highest priority rule will be
+ * used.
+ *
+ * @see git_attr_foreach.


I don't think there should be a trailing dot here?

Well, I think it reads better, but I checked and the usage is clear. I'll change it, though it seems docurium doesn't know about @see anyways…

We do have some special syntax for referring to other functions, I just always forget about it... and right now I cannot find any examples for it, either. Maybe prefixing it with an @? No idea...

I haven't been able to pinpoint a specific syntax in the docurium code, or any specific behavior w.r.t javadoc comments for that matter. As far as I can see, it checks function arguments against the list of known types and build links that way, but it only does this on functions. I've tried extending it to struct fields to no avail.

pks-t · 2018-02-16T10:02:10Z

include/git2/worktree.h

+/**
+ * Worktree add options structure
+ *
+ * Zero out for defaults.  Initialize with `GIT_WORKTREE_ADD_OPTIONS_INIT`


We shouldn't recommend zeroing out the struct, but only using GIT_WORKTREE_ADD_OPTIONS_INIT or the corresponding function, I guess.

IIRC this is copy-pasted from git_checkout_options. So what about something like :

/** * $STRUCT_DESCRIPTION * * Initialize with `$STRUCT_INIT_MACRO`. Alternatively, you can * use `$STRUCT_INIT_FN`. * * @see $STRUCT_USERS */

and I take a look to make sure all conform to this style ?

I expected that this was copied from somewhere else, but was too lazy to double-check :P Your proposal would certainly be fine with me, and removing references to zeroing out the structure are definitly welcome.

Agreed with @pks-t, and I like this text you've provided.

pks-t · 2018-02-16T10:02:33Z

include/git2/worktree.h

+/**
+ * Worktree prune options structure
+ *
+ * Zero out for defaults.  Initialize with `GIT_WORKTREE_PRUNE_OPTIONS_INIT`


Same here wrt zeroing out the struct.

pks-t · 2018-02-16T10:04:05Z

include/git2/worktree.h

@@ -180,7 +180,7 @@ typedef enum {
 typedef struct git_worktree_prune_options {
 	unsigned int version;

-	uint32_t flags;
+	git_worktree_prune_t flags;


This is not correct, though. An enum should always have a valid enum value, only, and not be used as a field of bits. As we're ORing multiple flags into this field this has to bee an uint32.

Right, I missed the ORing 🙄. Will drop from patchset. I was trying to get nice a link to show up, so I'll make it a doc-comment instead.

tiennou · 2018-02-20T01:19:43Z

Rebased, removed the worktree change, mass-rewritten the options_init comments, fixed a few more things, and merged in my changed which requires upstream support (PR).

This fixes #4495, #4213, makes most of the stuff in git2/sys/ visible, and changes the styling of structs for clarity (fixes #3779).

Some examples :

docs for git_transaction
some git_branch functions show up (the index registers them as API changes).
git_odb_backend/#3779 struct is fancier
it doesn't drop undocumented and/or incomplete structs.

See my doc branch here.

Some things I don't quite like : I get many errors when docuriuming old tagged releases, and I don't think they can be fixed, or even if it's worth the pain of doing workarounds. As far as I can tell, there are no severe losses in documentation vs. the vanilla docurium.

pks-t

Looks all good to me, I noticed one minor typo though. @carlosmn, as you're the one handling doc generation most of the time: do you have any comments?

pks-t · 2018-03-26T09:03:47Z

include/git2/transaction.h

@@ -8,6 +8,7 @@
 #define INCLUDE_git_transaction_h__

 #include "common.h"
+#include "types.h"


Hum. Good enough for now, I'd say. I feel like we should just include "types.h" in "common.h", as nearly every header wants "types.h" to be included. Can be done in a separate PR, though

👍 on that. I fear the next time an header is added, it will be forgotten and the clang-parse phase of docurium will get incomplete results.

pks-t · 2018-03-26T09:05:38Z

include/git2/attr.h

+ * @see git_attr_foreach.
+ *
+ * @param name The attribute name.
+ * @param value The attribute value. May be NULL is the attribute is explicitly


Typo: "s/is/if"

pks-t · 2018-03-27T08:50:59Z

include/git2/blame.h

 	size_t min_line;
+	/** The last line in the file to blame.
+	 * The default is the last line of the file.


Quick drive-by comment as I accidentally stumbled over these lines: the style should rather be

/** * Foobar */

pks-t · 2018-04-30T10:24:55Z

include/git2/describe.h

@@ -70,6 +69,16 @@ typedef struct git_describe_options {
 	GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \
 }

+/**
+ * Initialize git_describe_options structure


This one and git_describe_init_format_options both miss the leading short doc string that you're consistently using for the other init_options functions now

Otherwise docurium/clang chokes on the types, and ignores the documentation comments altogether.

Most files under `git2/sys` have their includes prefixed with `git2`. Since Docurium exports its input headers in a temporary directory without the `git2` prefix, all those headers fail to parse.

pks-t · 2018-06-01T11:17:42Z

Thanks @tiennou for handling this!

pks-t requested changes Feb 16, 2018

View reviewed changes

tiennou force-pushed the fix/docurium-missing-includes branch 2 times, most recently from df10416 to c520b52 Compare February 20, 2018 01:10

tiennou force-pushed the fix/docurium-missing-includes branch from e94310e to 90be04e Compare March 22, 2018 22:27

tiennou mentioned this pull request Mar 22, 2018

Quality of life tweaks libgit2/docurium#26

Closed

pks-t requested changes Mar 26, 2018

View reviewed changes

pks-t added the feedback provided label Mar 26, 2018

tiennou force-pushed the fix/docurium-missing-includes branch from 90be04e to 73ce3ea Compare March 26, 2018 18:25

pks-t reviewed Mar 27, 2018

View reviewed changes

pks-t reviewed Apr 30, 2018

View reviewed changes

tiennou added 15 commits May 7, 2018 21:50

docs: add buffer.h & oid.h to types.h

84bcae6

Otherwise docurium/clang chokes on the types, and ignores the documentation comments altogether.

docs: fix more missing includes

9657637

docs: fix some comment-marker typos

efad967

docs: move callback-specific documentation to the callback

f46c360

docs: missing documentation comment

8ee183a

docs: standardize comment block for git_*_init_options functions

ca5a15e

docs: move comment so docurium sees it

bf70fa4

docs: fix incorrect codeblock on output

29afb25

docs: correct defgroup

25e8a29

docs: change Docurium input directory

132f2ce

Most files under `git2/sys` have their includes prefixed with `git2`. Since Docurium exports its input headers in a temporary directory without the `git2` prefix, all those headers fail to parse.

docs: move blame options struct field comments

bf46d45

branch: typo

78ea5ad

attr: fix typo

3ec35d9

docs: fix comment style

c7b42f4

docs: standardize struct git_*_options comments

04c48af

tiennou force-pushed the fix/docurium-missing-includes branch from 8896716 to 04c48af Compare May 7, 2018 19:50

tiennou mentioned this pull request May 8, 2018

git_stash_save documentation missing from API docs #4647

Closed

pks-t merged commit bae6ed6 into libgit2:master Jun 1, 2018

tiennou deleted the fix/docurium-missing-includes branch June 18, 2018 22:18

snyk-bot mentioned this pull request Feb 23, 2020

[Snyk] Upgrade nodegit from 0.4.1 to 0.26.4 saurabharch/Breezeblocks#1

Open

snyk-bot mentioned this pull request Apr 22, 2020

[Snyk] Upgrade nodegit from 0.24.3 to 0.26.5 aminatakonate000/Graviton-App#4

Open

snyk-bot mentioned this pull request May 5, 2020

[Snyk] Upgrade nodegit from 0.24.3 to 0.26.5 Barnstorm-Online/ngp-openapi-generator#1

Open

Fix docurium missing includes #4530

Fix docurium missing includes #4530

Uh oh!

Conversation

tiennou commented Feb 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tiennou commented Feb 12, 2018

Uh oh!

pks-t left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tiennou commented Feb 20, 2018

Uh oh!

pks-t left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pks-t commented Jun 1, 2018

Uh oh!

Uh oh!

tiennou commented Feb 12, 2018 •

edited

Loading