Add support for "ErgoDoc"

accordproject / ergo

Programming Language for Smart Legal Contracts

https://accordproject.org/projects/ergo

Apache License 2.0

158 stars 55 forks source link

Add support for "ErgoDoc" #613

Open dselman opened 5 years ago

dselman commented 5 years ago

Provide a command line tool that can extract documentation metadata from structured comments for Ergo functions.

codetronaut commented 5 years ago

Please assign this to me. I will give my full on it. I only need little guidance.

jolanglinais commented 5 years ago

Great! @jeromesimeon you could probably point out a path forward.

codetronaut commented 5 years ago

Is this a better idea if I use "exiftool" for the metadata extraction for this issue. Please bear with me i am little new to this.

jeromesimeon commented 5 years ago

@codetronaut Great that you're interested to help!

I'm not really familiar with exiftool. My understanding of the suggested change was to support something along the lines of JSDoc for JavaScript: https://jsdoc.app

Maybe @dselman can elaborate a bit on what he was imagining?

jeromesimeon commented 5 years ago

A few initial pointers:

Extracting metadata from Ergo functions (e.g., names, type signatures) will require getting familiar with the Ergo AST which is in Coq (https://github.com/accordproject/ergo/blob/master/mechanization/Ergo/Lang/Ergo.v)
If we add annotations to the language in the @jsdoc style, this will mean making changes to that AST and to the Ergo parser which is on OCaml (https://github.com/accordproject/ergo/blob/master/extraction/src/ErgoParser.mly)
This issue could be addressed jointly with https://github.com/accordproject/cicero/issues/140

As a first step, I would make sure you can build Ergo from source following the DEVELOPERS instructions (those haven't been looked at in a while, so please open an issue if you have any difficulty!).

codetronaut commented 5 years ago

I will try my best.

codetronaut commented 5 years ago

@jeromesimeon I am little confused. I build the Ergo and after that, I am stuck. Basically, please tell me what should I do next. Because for the command-line tool i have to integrate the "https://github.com/accordproject/ergo/blob/master/mechanization/Ergo/Lang/Ergo.v" and check for the annotations add in @jsdoc right.

jeromesimeon commented 5 years ago

Hi @codetronaut I think it would be good to have a description for what the feature should be from a user point of view first? Depending on that we can then decide on the best implementation plan.

Note that this is not the easier first issue to try and tackle (which is why it was labelled as challenging). There are probably a few lower-hanging fruits in this repositories or in the other Accord Project repositories.

jolanglinais commented 5 years ago

@codetronaut what is the status of this? I'm opening it back up in the meantime.