search

microsoft / ChakraCore-wiki

A mirror of the ChakraCore wiki to enable pull requests on the Wiki.
https://github.com/Microsoft/ChakraCore/wiki
Other
22 stars 30 forks source link

Document missing APIs #57

Closed rhuanjl closed 6 years ago

rhuanjl commented 6 years ago

Picking up from discussion in https://github.com/Microsoft/ChakraCore/issues/5615

This PR adds the APIs from ChakraCore.h that were missing from the wiki.

I wanted some experience at parsing so I've been working on a script to generate all of the wiki's reference pages based on the CC headers - it's not finished yet, it can currently only read ChakraCore.h and only emits API pages - but thought it was worth adding the missing APIs now.

Note I found several other differences between the headers and the wiki which I've left out of this as unsure which should be updated (headers or wiki) - I may revisit those later.

Additionally the documentation for some of this APIs seems slightly sparse - and could perhaps do with expanding. For now seemed better to have something than nothing though.

dilijev commented 6 years ago

@rhuanjl please feel free to share that script you're working on. We'd love to be able to use something like that on an ongoing basis to keep the comments and the wiki in-sync (ideally both ways, but comments-to-docs is the most important direction).

rhuanjl commented 6 years ago

My script can handle all 4 headers now, it's javascript and runs in node (uses nodes' FS api for file read and write) - it's not very elegant I've never written anything like this before and had nothing to copy/base it on but it does seem to work.

If you want to try it you just have to edit the path information at the top of the file then run it with node (it needs a path to the headers to read and a path to the local clone of the wiki-repo to update)

(I'm afraid I've used some Regexs with look behinds in so it will need node-v8 it won't run in node-chakracore.)

One limitation is that for the windows APIs no way to get the alternate cross-platform equivalent from the data in ChakraCommonWindows.h so have to put placeholder text for that - other than that I think this does about what it needs to in terms of header to wiki.

EDIT: also noticed it's formatting is not sufficient for the more complex remarks blocks - e.g. doesn't handle the JSON snippets for some of the debug APIs well at all - I'll try and sort this later.

Running this identifies various differences additional to this PR.

Link to script: https://gist.github.com/rhuanjl/c82e80c7bc074ba791ef4ea083f4d649

liminzhu commented 6 years ago

:shipit: