search

BlakeGuilloud / ganon

A javascript library
MIT License
92 stars 196 forks source link

Figure out a way to display all of our methods #271

Open BlakeGuilloud opened 6 years ago

BlakeGuilloud commented 6 years ago

I think it would be really cool to have some sort of centralized resource where we could see all of the methods that have been created in this project. Kind of like an API doc.

It would be really cool to do this programmatically so we don't have to maintain it.

I figure we could write a script that reads the files of our lib folder, similar to the way that lib/index.js does currently, but it writes to a JSON file that lives within the app. We could then fetch from the JSON file and render it into some sort of front end. I think the stretch goal here would be to have the script first check the key it's updating, and not update it if it already has data attached. This would allow us to fill in a "description" property for each method (I don't see a way of doing that programmatically) that would not be overwritten the next time the script was run. The description would be additional data that we could display to the front end. The object could also contain data like "lastUpdatedAt" or "category". Something along those lines.

// data.json
{
  sum: {
     description: 'Adds the first two parameters.',
  },
  difference: {
     description: '',
  }
}

This is just to bring up a talking point. If anyone has any thoughts on this, please feel free to share them! cc @ktilcu @andreasgruenh @ contributors!!

luisvillalba commented 6 years ago

Good point, IMHO I think it would be ideal to handle everything from jsdocs that way we could use something like this to extract the documentation and put it in a template. This means we would need to refactor some functions to have proper jsdocs annotation.

BlakeGuilloud commented 6 years ago

Nice @luisvillalba ! I think you're onto something here. That is a really cool package. I'm gonna leave this one here too: https://github.com/jsdoc2md/jsdoc-to-markdown/

It looks like it utilizes the one you mentioned.

BlakeGuilloud commented 6 years ago

And yeah- a pretty major refactor would have to happen, but it could happen in chunks.

FranceJ commented 6 years ago

@BlakeGuilloud I'd be happy to start working through some of the methods and adding in docstrings. Not sure how far I'll get but I can do some of the grunt work. I'd make sure to only touch completed methods to avoid conflicts.

BlakeGuilloud commented 6 years ago

That would be awesome @FranceJ ! Feel free to reach out here with any questions or email me: blake.guilloud@gmail.com

Thanks man!!