[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

documentation as source

Randy W. Sims

10/12/2004 2:59:00 AM

Are there any Ruby modules that allow documentation to act as source
code? I was thinking of the problem of how souce code sometimes diverge
from its documentation. So maybe there could be a way to specify the
interface: the number of arguments and their types in the documentation,
and possibly pre- and post-conditions, and then the documentation would
be turned into code at runtime. I guess this would be implemented
something like Perl's source filters[1]. Possibly some constants and
such could be defined this way as well, version numbers, etc.

I'm not sure if this is a good idea or not; I haven't completely thought
it through. It seems like I've read about this being done before in some
other langage, but a brief search hasn't turned up anything.

Any thoughts?

Randy.

1. <http://perldoc.com/perl5.8.4/pod/perlfilte...
58 Answers

Jamis Buck

10/12/2004 3:10:00 AM

0

Randy W. Sims wrote:
> Are there any Ruby modules that allow documentation to act as source
> code? I was thinking of the problem of how souce code sometimes diverge
> from its documentation. So maybe there could be a way to specify the
> interface: the number of arguments and their types in the documentation,
> and possibly pre- and post-conditions, and then the documentation would
> be turned into code at runtime. I guess this would be implemented
> something like Perl's source filters[1]. Possibly some constants and
> such could be defined this way as well, version numbers, etc.
>
> I'm not sure if this is a good idea or not; I haven't completely thought
> it through. It seems like I've read about this being done before in some
> other langage, but a brief search hasn't turned up anything.
>

I haven't seen it done in Ruby, but the general idea is called "literate
programming". If you google for that term, you'll find lots of information.

I'm not a big supporter of the idea, though I've never done more than
tinker with it. I'd be curious to see what you come up with if you do
find a way to do it in Ruby, though.

- Jamis

--
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck...

T. Onoma

10/12/2004 3:28:00 AM

0

On Monday 11 October 2004 10:59 pm, Randy W. Sims wrote:
| Are there any Ruby modules that allow documentation to act as source
| code? I was thinking of the problem of how souce code sometimes diverge
| from its documentation. So maybe there could be a way to specify the
| interface: the number of arguments and their types in the documentation,
| and possibly pre- and post-conditions, and then the documentation would
| be turned into code at runtime. I guess this would be implemented
| something like Perl's source filters[1]. Possibly some constants and
| such could be defined this way as well, version numbers, etc.

With duck-typing this is difficult. I wrote a method probe that tries to
figure out these method signatures, but it is incomplete because Ruby is not
100% reflective (at least not from the inside out).

Of course you're talking about putting these in documentation and generating
code. I suggest maybe going the other way around.

T.

Ara.T.Howard

10/12/2004 3:59:00 AM

0

Robert Klemme

10/12/2004 7:12:00 AM

0


"Randy W. Sims" <ml-ruby@thepierianspring.org> schrieb im Newsbeitrag
news:416B486B.3020102@thepierianspring.org...
> Are there any Ruby modules that allow documentation to act as source
> code? I was thinking of the problem of how souce code sometimes diverge
> from its documentation. So maybe there could be a way to specify the
> interface: the number of arguments and their types in the documentation,
> and possibly pre- and post-conditions, and then the documentation would
> be turned into code at runtime. I guess this would be implemented
> something like Perl's source filters[1]. Possibly some constants and
> such could be defined this way as well, version numbers, etc.
>
> I'm not sure if this is a good idea or not; I haven't completely thought
> it through. It seems like I've read about this being done before in some
> other langage, but a brief search hasn't turned up anything.
>
> Any thoughts?

Two things come to mind:

1. literate programming (as others have mentioned already): there was a
recent thread here about the topic.

2. design by contract (DbC): there is a (experimental?) implementation of
DbC - I think by Andy Hunt.

Kind regards

robert

>
> Randy.
>
> 1. <http://perldoc.com/perl5.8.4/pod/perlfilte...
>
>
>

Niklas Frykholm

10/12/2004 7:43:00 AM

0

Jamis Buck wrote:
> Randy W. Sims wrote:
>
>> Are there any Ruby modules that allow documentation to act as source
>> code?
>
> I haven't seen it done in Ruby, but the general idea is called "literate
> programming". If you google for that term, you'll find lots of information.

If you want to try out literate programming, I recommend the "Leo"
editor. It's an hierarchical text editor with features for literate
programming. Leo is written in our "sister language" Python, but it
isn't really tied in to any particular programming language. You can use
Leo to write Ruby, C, Pascal, PHP, LaTeX, HTML or whatever you want.
The web site is:

http://webpages.charter.net/edreamleo/...

I've toyed a bit with literate programming, but I'm not really sold on
the idea. I guess my problem with "documentation as source" (or even
with "source as documentation", but that is a smaller gripe) is the
notion that a program only has one "story". Usually, I find that in my
programs there are many different stories: a story for a beginner user,
a story for an expert user, a story for someone who wants to extend the
module, a story for someone who wants to hack it, a story for someone
who wants to understand and study the technology behind it. And of
course, there can be stories can be in different languages. Trying to
put all these stories as well as the source code in the same document
tends to be confusing, at least for me.

But even if you don't use literate programming, Leo by itself is a great
tool for organizing source code and text. You should check it out.

// Niklas

Alexander Kellett

10/12/2004 8:31:00 AM

0

On Tue, Oct 12, 2004 at 11:59:02AM +0900, Randy W. Sims wrote:
> Are there any Ruby modules that allow documentation to act as source
> code? I was thinking of the problem of how souce code sometimes diverge
> from its documentation. So maybe there could be a way to specify the
> interface: the number of arguments and their types in the documentation,
> and possibly pre- and post-conditions, and then the documentation would
> be turned into code at runtime. I guess this would be implemented
> something like Perl's source filters[1]. Possibly some constants and
> such could be defined this way as well, version numbers, etc.

one thing i'd like to have in ruvi is good integration
with the version control systems. this includes the ability
to mark sections of documentation (and possibly there
dependancies if they are documented) as persistantly
invalidated when code is changed. i'd like this system
to be used for testcasing also, so a dependancy tree
between the testcases and the code they test is constructed,
therefore testcases that should possibly be added to could
be highlighted. really experimental stuff. it'll be years
before i get anything working nicely i guess. but its one
of the big aims :)

mvg,
Alex

Randy W. Sims

10/12/2004 8:50:00 AM

0

Jamis Buck wrote:
> Randy W. Sims wrote:
>
>> Are there any Ruby modules that allow documentation to act as source
>> code? I was thinking of the problem of how souce code sometimes
>> diverge from its documentation. So maybe there could be a way to
>> specify the interface: the number of arguments and their types in the
>> documentation, and possibly pre- and post-conditions, and then the
>> documentation would be turned into code at runtime. I guess this would
>> be implemented something like Perl's source filters[1]. Possibly some
>> constants and such could be defined this way as well, version numbers,
>> etc.
>>
>> I'm not sure if this is a good idea or not; I haven't completely
>> thought it through. It seems like I've read about this being done
>> before in some other langage, but a brief search hasn't turned up
>> anything.
>>
>
> I haven't seen it done in Ruby, but the general idea is called "literate
> programming". If you google for that term, you'll find lots of information.

Doh! That's the term I've been trying to think of. Thanks.

> I'm not a big supporter of the idea, though I've never done more than
> tinker with it. I'd be curious to see what you come up with if you do
> find a way to do it in Ruby, though.

I'm not looking for anything comprehensive. Just something to reduce the
redundencies that often exist at least for the common cases. Just small
stuff like (if you'll forgive a perl example, I'm more familiar with it)
perl modules often declare a version:

our $VERSION = 1.03;

Then somewhere else in the POD documents, you'd have:

=head1 VERSION

blah blah version 1.03

=cut

So anytime you change the version, you have to remember to change it in
multiple places. Ideally, you could just change the docs.

This is mostly just a curiosity at the moment. I just thought I'd ask if
anything like that was available that I could play with.

Randy.

Brian Schröder

10/12/2004 9:13:00 AM

0

Randy W. Sims wrote:
> Jamis Buck wrote:
>
>> Randy W. Sims wrote:
>>
>>> Are there any Ruby modules that allow documentation to act as source
>>> code? I was thinking of the problem of how souce code sometimes
>>> diverge from its documentation. So maybe there could be a way to
>>> specify the interface: the number of arguments and their types in the
>>> documentation, and possibly pre- and post-conditions, and then the
>>> documentation would be turned into code at runtime. I guess this
>>> would be implemented something like Perl's source filters[1].
>>> Possibly some constants and such could be defined this way as well,
>>> version numbers, etc.
>>>
>>> I'm not sure if this is a good idea or not; I haven't completely
>>> thought it through. It seems like I've read about this being done
>>> before in some other langage, but a brief search hasn't turned up
>>> anything.
>>>
>>
>> I haven't seen it done in Ruby, but the general idea is called
>> "literate programming". If you google for that term, you'll find lots
>> of information.
>
>
> Doh! That's the term I've been trying to think of. Thanks.
>
>> I'm not a big supporter of the idea, though I've never done more than
>> tinker with it. I'd be curious to see what you come up with if you do
>> find a way to do it in Ruby, though.
>
>
> I'm not looking for anything comprehensive. Just something to reduce the
> redundencies that often exist at least for the common cases. Just small
> stuff like (if you'll forgive a perl example, I'm more familiar with it)
> perl modules often declare a version:
>
> our $VERSION = 1.03;
>
> Then somewhere else in the POD documents, you'd have:
>
> =head1 VERSION
>
> blah blah version 1.03
>
> =cut
>
> So anytime you change the version, you have to remember to change it in
> multiple places. Ideally, you could just change the docs.
>
> This is mostly just a curiosity at the moment. I just thought I'd ask if
> anything like that was available that I could play with.
>
> Randy.
>
Only for this special case, you could use
# blah blah blah
# This is
VERSION = '1.03'
# blah blah blah.

Which is quite readable and valid ruby code.

regards

Brian

--
Brian Schröder
http://ruby.brian-sch...

gabriele renzi

10/12/2004 9:23:00 AM

0

Randy W. Sims ha scritto:


> This is mostly just a curiosity at the moment. I just thought I'd ask if
> anything like that was available that I could play with.
>

I'd check if RDoc can solve your problems.. then patch it to do it if it
does'nt :)

Bil Kleb

10/12/2004 10:44:00 AM

0

Randy W. Sims wrote:
> Are there any Ruby modules that allow documentation to act as source
> code?

require 'test/unit'

Then code test-first and you'll have executable documentation.

Code test-first with a partner, and you'll have /sane/ executable
documentation.

When test/unit2 appears, tests will become even more like documentation.

I've played with Literate Programming for over a decade and found
that it nearly always violates the DRY principal. As a result, it
eventually gets out of sync and begins to lie.

Regards,
--
Bil Kleb, Hampton, Virginia
http://fun3d.lar...