help.lasso for Knop for Lasso 9 about knop HOT 7 OPEN

Have you thought about utilizing Lasso 9's doc comments? Here's a quick example grabbing some doc comments in the Lasso 9 core code itself (Run this from the command line):

LASSO9_RETAIN_COMMENTS=1 lasso9 -s "with m in sys_listUnboundMethods where #m->docComment->size > 0 select #m->docComment"

from knop.

Thanks for the example. It is part of our consideration. This may be one piece of the overall puzzle. However it's pretty much the same as using -description, unless I am missing something.

I know that the use of javadoc syntax was tossed about years ago for auto-generation of documentation, but I have no idea what happened to that idea, whether it was abandoned or set aside for higher priorities within LassoSoft and never developed further.

from knop.

It is like -descripiton but it gives you the ability to also document traits. My thought is that the doc comments would contain a simple markup language. I'm not sure if javadoc markup has been implemented or not, but if not, then that gives you the ability to use whatever markup you want.

On another note, in terms of getting method / type signatures in a programatic fashion, it looks like this may have some gems in it:
http://source.lassosoft.com/svn/lasso/lasso9_source/trunk/reference_generator.lasso
(Take a look at [reference_makeDecoratedMethodName], for instance.)

from knop.

Yeah, there is some good stuff in there, but a lot more questions. What is the bitTest method? How do we get the return type of a method?

Anyway, back to the point of what markup to use, we're discussing which is best. Markdown is simple and can be instantly previewed in BBEdit, but limited in features. ReStructuredText has a lot of flexibility and is easy to use, but requires an interpreter to render it to a given output (for which there are many options).

Javadoc may be another option. Here's some information on it.

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

from knop.

I've been doing additional research about which markup syntax to use going forward. I am convinced that the best option is ReStructuredText (one word or "RST") going forward. The reasons are:

• easy to use
• supports tables (markdown does not)
• widely supported
• GitHub can render RST files in repositories as HTML. See https://github.com/github/gollum
• pandoc can easily convert existing documentation to RST. See http://johnmacfarlane.net/pandoc/
• Using pandoc, RST can be output to numerous formats, including HTML and PDF.
• restview is a Python tool that enables one to preview RST in a web browser or BBEdit's Preview via HTML Web Sites without sending it through a processor, restview: http://mg.pov.lt/restview/
• Sphinx's primary input is RST.

from knop.

I would be interested in helping to create a Lasso 9 domain for Sphinx. Have you made any progress on this? I'm starting to read through Sphinx documentation.

from knop.

Thanks to Brad, we've made significant progress on this issue.

https://github.com/knop-project/knop/tree/master/knop9/docs

I think we might be better off breaking this into different issues going forward and categorizing/tagging the issues as "docs".

from knop.