Multiple docstring lines
[1/5] from: tim-johnsons::web::com at: 4-Jun-2007 15:29
For years, I've been irritated by the way that emacs handles multiple line
strings for syntax highlighting - IOWS, it just doesn't work that well.
Soo.... this is what I tried:
With one large file as a test case - a "library" of reusable routines -
I replaced multiple line docstrings with multiple lines of docstrings.
Here's an example:
swaps: def[{Swaps pairs in block. Block must be of even length.
Example: swaps[2 1 4 3 6 5] => [1 2 3 4 5 6]}[catch]
blk[block!]
][
if not even? (length? blk)[toss["'blk argument must be of even length."]]
foreach [a b] blk yield[reduce[b a]]
]
;; with multiple docstrings:
swaps: def["Swaps pairs in block. Block must be of even length."
" Example: swaps[2 1 4 3 6 5] => [1 2 3 4 5 6]"[catch]
blk[block!]
][
if not even? (length? blk)[toss["'blk argument must be of even length."]]
foreach [a b] blk yield[reduce[b a]]
]
I then created a function called 'helpn by copying the source for 'help
and replacing:
either string? pick args 1 [
print [tab first args]
args: next args ......
;; with
either string? pick args 1 [
while[string? pick args 1][
print [tab first args]
args: next args
]
As a result 'helpn picks up the multiple lines, and since the routines
in this file are used very widely in my code, I have not yet seen any
problems. It looks like rebol ignores any strings when parsing the
interface specification block for any function.
Now my syntax highlighting is no longer scrambled, and I find I have
more flexibility in formating both the code and the resulting output
from helpn.
comments are welcome. If I run into any problems with this strategy,
I will post the issues. So far, it looks workable.
Tim
[2/5] from: gregg::pointillistic::com at: 5-Jun-2007 10:40
Hi Tim,
TJ> For years, I've been irritated by the way that emacs handles multiple line
TJ> strings for syntax highlighting - IOWS, it just doesn't work that well.
TJ> Soo.... this is what I tried: ...
TJ> swaps: def["Swaps pairs in block. Block must be of even length."
TJ> " Example: swaps[2 1 4 3 6 5] => [1 2 3 4 5 6]"[catch]
TJ>...
I'm leery of this, only because I think the func spec is designed for
a single doc string, and the fact that it works may just be due to the
current implementation.
-- Gregg
[3/5] from: tim-johnsons::web::com at: 5-Jun-2007 11:59
On Tuesday 05 June 2007, Gregg Irwin wrote:
> Hi Tim,
> TJ> For years, I've been irritated by the way that emacs handles multiple
<<quoted lines omitted: 7>>
> a single doc string, and the fact that it works may just be due to the
> current implementation.
You should be. So am I. That's why I made this change to one file alone,
and backed it up. And that file is not going to be used in an
implemented project.
*But* I have found no documentation on this subject. This should be clarified
by the developers. As a side note, I'm always interested in what rebol can do,
and one of the most intriguing statments I've come across regarding rebol is:
The interface spec is an example of a dialect
(sic), it would make for an
interesting discussion to examine the interface spec further.
thanks
tim
[4/5] from: gregg:pointillistic at: 6-Jun-2007 9:37
Hi Tim,
TJ> "The interface spec is an example of a dialect" (sic), it would
TJ> make for an interesting discussion to examine the interface spec
TJ> further.
Agreed. I think RT knows that documentation is more important than
ever, and that the holes in R2 docs need to be filled.
-- Gregg
[5/5] from: tim-johnsons:web at: 6-Jun-2007 8:27
On Wednesday 06 June 2007, Gregg Irwin wrote:
> Hi Tim,
>
> TJ> "The interface spec is an example of a dialect" (sic), it would
> TJ> make for an interesting discussion to examine the interface spec
> TJ> further.
>
> Agreed. I think RT knows that documentation is more important than
> ever, and that the holes in R2 docs need to be filled.
I'm off work here today, but starting tomorrow I will add a multiple
line docstring to my most used function, I will be crunching it tomorrow,
any problem should show up, methinks.
cheers
tim
Notes
- Quoted lines have been omitted from some messages.
View the message alone to see the lines that have been omitted