Rough draft of how the docs may look. #258

Open
wants to merge 1 commit into
from

Conversation

Projects
None yet
3 participants

Updated lib/luvit/querystring.lua to include inline docs in GitHub
Markdown format. There are a couple of points about this discussed
below. Also included is a stand-alone document for the querystring
module, again in GitHub Markdown format.

Regarding the inline docs, I have chosen to demark them using a
triple dash block comment, i.e: ---[[ .... ---]]. This is so it is
easier to include code snippets in the docs, which themselves may
include block comments using the default double dash format.

This does work to some effect, however the current doc scraper misses
out the first doc block comment and I'm not sure why, also some stray
double dashes appear.

Rough draft of how the docs may look.
Updated libs/luvit/querystring.lua to include inline docs in GitHub
Markdown format. There are a couple of points about this discussed
below. Also included is a stand-alone document for the querystring
module, again in GitHub Markdown format.

Regarding the inline docs, I have chosen to demark them using a
triple dash block comment, i.e: ---[[ .... ---]]. This is so it is
easier to include code snippets in the docs, which themselves may
include block comments using the default double dash format.

This does work to some affect, however the current doc scraper misses
out the first doc block comment and I'm not sure why, also some stray
double dashes appear.

Why is this example twice? Wouldn't once be enough.

The format is fine. I'm not picky about docs. The main thing is we need some written and kept up to date.

Owner

robsearles replied Jun 25, 2012

Why is this example twice? Wouldn't once be enough.

I was trying to demonstrate the difference between not specifying sep and eq in comparison if you do.

Probably not important for this particular function as it is so simple, but with more complex functions it may be a good idea to have specific examples of any optional parameters?

Is this just too verbose?

Oh, I didn't notice the difference. A little verbosity is fine, just fine ways to keep it DRY. Maybe only show the parts that changed in the second example?

Member

kaustavha commented Oct 29, 2015

So the latest in the Docs series of developments is this repository:
https://github.com/luvit/luvit-docs
Its derived from nodejs' docs and works similarly.
They currently provide a decent high level overview of luvit, albeit much remains to be done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment