Adding docs for NodeGit #1350
Adding docs for NodeGit #1350
Conversation
generate/README.md
Outdated
| @@ -0,0 +1,21 @@ | |||
| ## /generate | |||
|
|
|||
| The scripts and templates in this dir, help generate the source code and tests for NodeGit. The major components of generate are: | |||
generate/templates/README.md
Outdated
| If generated code does not accurately wrap the libgit2 calls, you might want to consider implementing manual templates in the following cases: | ||
|
|
||
| #### 1. Performance | ||
| > Everytime the library switches between the C land and the JS queue thread, there is a penalty in performance. If the generated code switches frequently, it might be better option to use manual templates. |
There was a problem hiding this comment.
This might be better:
Everytime the library switches between C land and the javascript thread, there is a penalty in performance. If in practice the usage of a method in libgit2 requires crossing the c/javascript boundary frequently, it might be better option to use manual templates. An example being
Revwalk::FastWalk.
generate/templates/README.md
Outdated
| > The generated code sometimes does not handle structures that are inter-dependant. Perfect example would be convenient_hunks. Hunks references a file pointer and diff lines that are dependant on it. If persisted, it would lock the file. If garbage collected, the diff lines would cause seg fault errors. Anytime a custom solution is required, that would be hard for generated code to implement, manual templates should be used. | ||
|
|
||
| #### 3. Odd cases | ||
| > If a new pattern exists in libgit that would be difficult to implement using generated code, manual templates can be used for one-off cases. Typically generated code takes care of most patterns seen in libgit, but if function signatures do not follow typical pattern, manual templates could be used. Example: git_filter. |
There was a problem hiding this comment.
git_remote_ls is another good example.
generate/templates/README.md
Outdated
| ----- | ||
| ## Implementing manual templates | ||
|
|
||
| #### 1. Copy generated .cc and .h files to *generate/templates/manual/* |
There was a problem hiding this comment.
Typically, we don't have generated files to copy when we need to write manual templates.
There was a problem hiding this comment.
You're right, modified this
generate/templates/README.md
Outdated
|
|
||
| <br /> | ||
| ----- | ||
| ## Implementing manual templates |
There was a problem hiding this comment.
This particular list of instructions you've provided only talks about how to add a manual class/struct. What about manual functions?
There was a problem hiding this comment.
I didn't use manual functions, I'll dig around and figure out how to write and use them
lifecycleScripts/README.md
Outdated
| @@ -0,0 +1,5 @@ | |||
| ## /lifecycleScripts | |||
|
|
|||
| These scripts are responsible for downloading the right dependencies, configuring vendors, and all other dependencies that are required to build, generate and clean the module. | |||
lib/README.md
Outdated
| @@ -0,0 +1,3 @@ | |||
| ## /lib | |||
|
|
|||
| Contains wrappers to abstract the internals of the JavaScript part of NodeGit Module. | |||
There was a problem hiding this comment.
This is very vague, instead...
Contains javascript extensions for the generated NodeGit modules. Any additional behavior on top of the standard libgit2 behavior will be found here.
test/README.md
Outdated
| @@ -0,0 +1,17 @@ | |||
| ## /test | |||
|
|
|||
| Contains all the test scripts, runner and keys for running the tests. | |||
generate/templates/README.md
Outdated
| > Everytime the library switches between the C land and the JS queue thread, there is a penalty in performance. If the generated code switches frequently, it might be better option to use manual templates. | ||
|
|
||
| #### 2. Saftey | ||
| > The generated code sometimes does not handle structures that are inter-dependant. Perfect example would be convenient_hunks. Hunks references a file pointer and diff lines that are dependant on it. If persisted, it would lock the file. If garbage collected, the diff lines would cause seg fault errors. Anytime a custom solution is required, that would be hard for generated code to implement, manual templates should be used. |
There was a problem hiding this comment.
This might be better:
The generated code sometimes does not handle structures that are interdependent. An example would be git_patch and git_diff. A git_patch's memory is owned by git_diff, and that includes all of the children of git_patch, as well. So a git_diff_hunk, git_diff_line, and git_patch all are owned by a git_diff, and when that git_diff is deleted, all the memory for any patches, hunks, or lines that are in use as NodeGitWrappers are now corrupted. Further, a git_diff keeps a file handle open for its entire lifespan, which can lead to NodeGit holding onto file locks in Windows. Due to both of these compounding issues, we wrote manual templates to shift ownership away from a git_diff to git_patch, git_diff_hunk, and git_diff_line and also shorten the lifespan of a diff.
generate/templates/README.md
Outdated
|
|
||
| ## Why? | ||
|
|
||
| If generated code does not accurately wrap the libgit2 calls, you might want to consider implementing manual templates in the following cases: |
There was a problem hiding this comment.
I think we can lop this off and jump straight into the list.
|
@implausible These changes look like they could be really helpful in NodeGit. Aside from the examples page, the additions seem worthwhile to me. |
|
nice work @mohseenrm. These would be helpful in my opinion! |
No description provided.