API guide is truncated. Carter should finish the sentences in the comments and docs

[stephenjlewis]

api-guide.md seems to cut short partially through -- here's the tailing section:

Before you get lost, the current set of live modules in the code base that have any useful information are:
    .     .     .
    .     .     .
    Numerical.Array.Locality
    Numerical.Array.Address
    Numerical.Internal.Data.Vector.Pair

For those who just wish to

And that's the end of things.

[cartazio]

Yeah... I do that occasionally in the code base, and its something that REALLY needs to be fixed in the comments and docs throughout sometime after I do the next batch of commits and before I declare public alpha. If you want to point out other places i do that in this ticket, that'd be awesome

that document in particular is/was/will be a wee "guidebook" for what modules to look at to understand end user interface vs internals vs whatever. Or at least thats the idea. But please feel welcome to ask questions here on the issue tracker, or on irc.

[stephenjlewis]

Running ag -G ".*\.md" -B 1 "^ *[^#*-\[\]\n][^\[\]#.):\!]* *$\n\n" in the root of the source tree finds a few more examples of documentation paragraphs which don't terminate in proper punctuation (some, including the first, are merely missing a period):

README.md
25-Numerical Haskell is an effort to bring great numerical computation and data analysis
26:tooling to haskell, and be the best possible platform for sophisticated efforts in those same domains
27:
28:## What array Formats are Supported

notes.md
15-
16:would like to at some point change things so matrix mult and dot product
17:can be defined by by any 
18:
19:## For now
28-## deep embedding backends
29:wont be supported till after "version zero", though will soon afterwards, but 
30:some of the scaffolding will be visible in version zero
31:
32:## why 
60-
61:example of nested layout
62:
63:col major of 2x2 rowmajor (2dim)

bug.md
12-If possible/applicabe please also include: your OS version, GHC version, the output of
13:`GHC --info`, what versions of the numerical-haskell libs you have installed,
14:what versions of the dependencies are installed, and also the relevant versions 
15:

Here's a similar regex that finds all block comments without terminating paragraph punctuation: be warned: there's lots of noise, since many of your notes lack punctuation, even aside from those with unfinished thoughts.

ag -G "./*.hs" "\{- *[^#@](.*[^.\!)(]\n+[^a-z]?)*\-\}"

It returns about 23% of block-commented lines, as found by ag -G "./*.hs" "\{- *[^#@]([^\}\{]*\n*)*\-\}", a regex which is mostly right, although it excludes a few lines with literal { or } characters.

[cartazio]

hehe, awesome! Many thanks! I very much appreciate this. theres definitely going to be a LOT of needed cleanup and documentation :)
(I will be resuming work soon, its just been on hold while sorting out OSS/intellectual property stuff at my current job)

[cartazio]

@stephenjlewis i'm getting back into the swing of things, i hope to have the docs and guides in more legible shape by mid-late may, if not sooner. If i ping you once its in better shape, would you mind doing a go over? (external feedback tends to be super handy etc )

[stephenjlewis]

Sure! I'm super busy with a bunch of projects for the next while, so it may be a few weeks before I find the time, but just let me know; I'll keep half an eye on your commits in the meantime.