Skip to content
Permalink
Browse files

Updated commenting on the documentation generation (#202)

* expanded on marty's start of commenting on documentation

* added editor support for org
  • Loading branch information
mariari committed Nov 22, 2019
1 parent 735b7cd commit bc69c93589b1a5d08706b5e9d7d0f99f586b42c8
Showing with 19 additions and 2 deletions.
  1. +1 −1 README.md
  2. +18 −1 doc/CONTRIBUTING.md
@@ -97,7 +97,7 @@ juvix interactive

[Ormolu](https://github.com/cryptiumlabs/ormolu) required for source formatting.

[Quicklisp](https://www.quicklisp.org/beta/) and [sbcl](http://www.sbcl.org/) required for the automatic generation of documentation in [doc/Code](https://github.com/cryptiumlabs/juvix/tree/develop/doc/Code).
[Quicklisp](https://www.quicklisp.org/beta/) and [sbcl](http://www.sbcl.org/) required for the automatic generation of documentation in [doc/Code](https://github.com/cryptiumlabs/juvix/tree/develop/doc/Code).

To open a REPL with the library scoped:

@@ -9,7 +9,24 @@ Contributions are welcome! Please consider the following guidelines.

## Documentation

Add a brief description of any module you create before the module and after pragmas. Start each line of the description with `--`. The first line of the description should be `--|`. E.g., see [this](https://github.com/cryptiumlabs/juvix/blob/15ca9e5e602d24cf09fe87fc059e3e0ee78ad6db/src/Juvix/Encoding/Encoding.hs#L3).
Add a brief description of any module you create before the module definition.
This can be placed before or after (more idiomatically) after file specific pragmas.
Much like haddock, the comments must begin with `--|` as the first comment and `--` for the consecutive lines.

The comment formatting follows [org formatting](http://ergoemacs.org/emacs/emacs_org_markup.html), Just note that
one should avoid adding headlines (* at the start of the line) as to avoid conflicts in generation.

Also try to keep each comment line below 82 characters long, breaking the line into a second line at the same indentation level
and on the next line will not newline any generation from the org file itself.

An example of this generation [can be seen here](https://github.com/cryptiumlabs/juvix/blob/15ca9e5e602d24cf09fe87fc059e3e0ee78ad6db/src/Juvix/Encoding/Encoding.hs#L3).

The best way to write the documentation is by getting an org mode extension and writing the comments in said extension.
- [atom](https://atom.io/packages/org-mode)
- [vim](https://github.com/jceb/vim-orgmode)
- [vscode](https://marketplace.visualstudio.com/items?itemName=tootone.org-mode)
- [emacs](https://orgmode.org/)
+ [emacs-in-buffer](http://pragmaticemacs.com/emacs/write-code-comments-in-org-mode-with-poporg/)

## Branch usage

0 comments on commit bc69c93

Please sign in to comment.
You can’t perform that action at this time.