More Detailed Haddock Documentation

[Ant13731]

Building off of the discussion from #2404, this is just to keep track of the progress of making more detailed haddock documentation.

1. augment the current Haskell sources with good Haddock comments, so that Drasil's own documentation has good descriptions of its own combinators
2. make some kind of hand-written HTML meta-document that points to the generated docs as a kind of roadmap.

Doing it this way "by hand" may give us some insights as to how we'd want such things documented, as a prelude to seeing if it can be done in Drasil itself.

Progress list (I'm not sure if example and data need to be checked, but I'll put them here anyway):

• [x] drasil-build documentation
• [x] drasil-code-base documentation
• [x] drasil-code documentation
• [x] drasil-data documentation
• [x] drasil-database documentation
• [x] drasil-docLang documentation
• [ ] drasil-example documentation
• [x] drasil-gen documentation
• [ ] drasil-gool documentation (skip this one for now)
• [x] drasil-lang documentation
• [x] drasil-metadata documentation
• [x] drasil-printers documentation
• [x] drasil-theory documentation
• [x] drasil-utils documentation
• [x] drasil-website documentation

Some of the above folders are too large to complete in one go, so I'll list more details of them below. For drasil-code:

• [x] Data
• [x] Language
  • [x] Chunk
  • [x] Code
    • [x] Imperative
      • [x] Build
      • [x] Doxygen
      • [x] GOOL
      • [x] Parsers
      • [x] Rest of Imperative files
    • [x] Rest of Code files
  • [x] Data
• [x] Test

For drasil-data:

• [x] Concepts
• [x] Equations
• [x] Quantities
• [x] Software
• [x] Theories
• [x] Units
• [x] rest of Drasil folder

For drasil-docLang:

• [x] DocLang
• [x] DocumentLanguage
• [x] Sections
• [x] rest of Drasil folder

For drasil-gool:

• [ ] LanguageRenderer
• [ ] rest of Drasil folder

For drasil-lang:

• [x] Chunk
• [x] Classes
• [x] Data
• [x] Development
• [x] Document
• [x] Expr
• [x] Label
• [x] NounPhrase
• [x] Sentence
• [x] Symbol
• [x] Uncertainty
• [x] URI
• [x] rest of files before README
• [x] rest of files after README

For drasil-printers:

• [x] HTML
• [x] Markdown
• [x] Plain
• [x] Printing
• [x] TeX
• [x] rest of Drasil folder

[JacquesCarette]

A good issue would list the files that need work, with a check-box beside it to show completion. Issues that involve a lot of work are sub-optimal, as they tend to take forever to get closed. Getting an indication of what's been done and what's left, mitigates that somewhat.

[balacij]

@JacquesCarette @smiths This one (+ it's derivative, #2753) looks like it could be good to close out. It's almost complete, and thanks to Anthony's amazing work shown above, there are tons of reference work!

[smiths]

Yes, @Ant13731 did some great work on the documentation! I noticed that drasil-example and drasil-gool are not checked off. When we close this issue, should we create issues for those two?

[balacij]

Yes, sorry! I should have been more clear. I meant to say that completing this ticket out could be a good starting task for the new students that will be working on Drasil.

[smiths]

Oh, I see. You used the wording "close out", which I interpreted as close, but you what you meant is someone can finish up this issue. I agree with you. This would be a good starter issue (after a bit of training on what is expected for the documentation - fortunately there are already many good examples in the current code.)