Documentation support for the Crystal Programming Language

[keplersj]

With the Crystal repository itself signed up for CodeTriage I thought it made be kinda nice to have the documentation triage feature work with Crystal code. I'm totally ready to help out implementing this, just point me in the right direction.

[schneems]

Thanks for reaching out! That would be really cool. Right now it only works for Ruby. Crystal would be the first, so there's no real how-to guide for getting non-ruby languages to work with our "docs". Ruby works by downloading the source code from Github then using YARD we process docs which stores them all in memory. Once that is done we loop through all the entities and then we store them in the database.

Other languages

To get started we would need the language you need to parse docs. My best guess is that we'll need to install additional languages when we deploy using buildpacks. Once we have crystal installed we'll need to process the docs. Then once we've processed we'll need to get it into the database.

Instead of needing to have crystal connect to the database and directly put records in the DB I think it would make sense if we had an intermediate format to write data do that other languages can use. Probably JSON. Then I can write some code that reads that serialized data and imports it into the database.

Right now there are three records we will store a DocMethod and a DocClass each of which can have many DocComment-s.

=> DocMethod(id: integer, repo_id: integer, name: string, line: integer, created_at: datetime, updated_at: datetime, doc_comments_count: integer, path: string, file: string, skip_write: boolean, active: boolean, skip_read: boolean)

=> DocClass(id: integer, repo_id: integer, name: string, created_at: datetime, updated_at: datetime, doc_comments_count: integer, line: integer, path: string, file: string)

=> DocComment(id: integer, doc_class_id: integer, doc_method_id: integer, comment: text, created_at: datetime, updated_at: datetime)

I realize that all languages won't have methods and classes, but I figured it was fine as a starting point.

We only email out DocMethod-s right now. If you select you want to "write" docs we send you a method with 0 comments, if you want to "read" docs you get a method with a comment attached.

What do you think?

How does this sound so far? Still interested? What assumptions have I made about Ruby that are totally not applicable to crystal? If you are interested let me know what you think about the proposal. I can start working on JSON de-serialization and docs.

[keplersj]

I think that sounds good. I've actually been working on JSON output of the documentation in the Crystal repository. crystal-lang/crystal#2772