[q]class documentation

Bermejo_Rodrigo · 11 April 2003 21:00

Hi all;
There are some (“native”) mechanism to add documentation into my class
code ?
something like …

class Myclass

    def doc   #or may ?
            d=" "
            d <<  <<-doc
              .---------------------------------------.
               >  Myclass:Just an exemple                         |
              .---------------------------------------.
               >  Methods:                                           
          >
               >  doc();Show Class Documentation        |
               >  reverse(string);reverse a string given |
                `---------------------------------------'        
            doc
             print d
     end
   
     def reverse(string)
         string.reverse
     end

end

···

–
-r.
def something_better_to_do
perl clean_this_large_txt.pl&
end

Austin_Ziegler2 · 11 April 2003 22:10

If you’re referring to a Python-like “document-string”, no. However:

# Just an example

class Myclass
# Reverses +string+.
def reverse(string)
string.reverse
end
end

You can then run this through rdoc and it will be documented.
Honestly, I can’t think of many times that programmatic access to
the documentation would be useful.

HOWEVER … the one time that I do need it is when I’m in irb. It
might be nice to have irb add an “ri” method to Object that does an
appropriate “ri” lookup…

-austin
– Austin Ziegler, austin@halostatue.ca on 2003.04.11 at 18:06:16

···

On Sat, 12 Apr 2003 06:00:30 +0900, Bermejo, Rodrigo wrote:

Hi all;
There are some (“native”) mechanism to add documentation into my
class code?

Matt_Lawrence · 25 April 2003 20:43

Ok, I’ve been looking at Marshal, PStore, Madelaine and mnemonic. None of
them seem to provide the simple and transparent mechanism that I’m looking
for.

I’d like to be able to do something like:

arr = PersistantArray.use("<filename>")
hash = PersistentHash.use("<filename>")

Where is the name of the file to read and write data from and
the resulting object has all of the methods of Array or Hash and all
changes to the Array of Hash are automatically stored. This would make if
much easier to restart programs that fail because of network or other
errors.

It’s quite possible that these capabilities already exist and I just don’t
know about them, I am quite a newbie at this wonderful language. I
wouldn’t even try to do this with Perl.

– Matt

Ryan_Pavlik1 · 25 April 2003 21:32

If you can hang on for a day or so, I’ll release Mephle on Monday.
I just added the ability to write non-networked apps a few nights ago,
along with a SQLite storage driver.

What’s Mephle? Well, let’s get to the part you want:

s = String.new_on(:volume, "abc")

What did this do? ‘s’ is now a String object stored in the volume
:volume (which is just a tag, see next), implicitly on $SERVER (more on
that later).

A volume is just a tag for a storage driver. You can add a
SQLiteStorage, which stores everything in a single file. (Also
included is MySQLStorage, which stores stuff in a MySQL db; useful for
larger apps.)

There is a “virtual directory” structure, so you can do this, too:

s = String.new_on("/strings/my_string", :default, "abcd")

Later, you can recover it by doing the following:

s = retrieve("/strings/my_string", :default)

The nice part is—just like you want—no worry about file formats, and
it’s all transparent. It’s even better than PersistantArray, though,
because any given type can be persisted. (Marshal is used
internally.)

Of course, this is just a small portion of what Mephle provides; you
also get nice network transparency:

$C = Mephle::Driver::TCPConnection("remotehost.com", 9000)
$C.open

s = Get($C, :default, "/strings/my_string")

Now ‘s’ is a remote reference. It will act and behave exactly like a
String, except any method calls happen on the remote object. Even
exceptions will be thrown across the network.

There are other nifty things too, like class_ and method_info
(code-accessible documentation), HTML widget library, automatic
interface generation for objects, and others. (Don’t worry, this is
not tied to HTML, but it does have extensive web interface support.)

Interested?

···

On Sat, 26 Apr 2003 05:43:03 +0900 Matt Lawrence matt@black-bart.net wrote:

Ok, I’ve been looking at Marshal, PStore, Madelaine and mnemonic. None of
them seem to provide the simple and transparent mechanism that I’m looking
for.

I’d like to be able to do something like:

arr = PersistantArray.use(“”)
hash = PersistentHash.use(“”)

–
Ryan Pavlik rpav@users.sf.net

“These monkeys of which you speak… are they mentally
deficient by human or monkey standards?” - 8BT

Gennady1 · 25 April 2003 21:37

You may want to take a look at mmap library at RAA, or directly at
http://moulon.inra.fr/ruby/mmap.html. It is memory mapped files
implementation, well done. Not exactly what you are asking for, however very
similar in intent.

Gennady.

···

----- Original Message -----
From: “Matt Lawrence” matt@black-bart.net
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Sent: Friday, April 25, 2003 1:43 PM
Subject: Persistant data

Ok, I’ve been looking at Marshal, PStore, Madelaine and mnemonic. None of
them seem to provide the simple and transparent mechanism that I’m looking
for.

I’d like to be able to do something like:

arr = PersistantArray.use(“”)
hash = PersistentHash.use(“”)

Where is the name of the file to read and write data from and
the resulting object has all of the methods of Array or Hash and all
changes to the Array of Hash are automatically stored. This would make if
much easier to restart programs that fail because of network or other
errors.

It’s quite possible that these capabilities already exist and I just don’t
know about them, I am quite a newbie at this wonderful language. I
wouldn’t even try to do this with Perl.

– Matt

gabriele_renzi4 · 25 April 2003 22:44

this could be completely wrong

I suppose that this is a work for persistence/prevalence layers, but I
don’t think thay would actually save each change.

But it seem to me that working this way you’ll have too many atomic
writings, and you’ll loose in performance.

The Madeleine/prevayler approach should be to save the state of the
application space with predefined time slices, while the persistence
layer approach should be about using save/retrieve methods, so you’ll
just have to add a obj.save the way you’ll use Marshal(obj,io).

Possibly this performance/fault_tolerance problem is the same of the
sync/async writing in filesystems, and a middle-way approach a-la
Madeleine could be , imho, a good thing

···

il Sat, 26 Apr 2003 05:43:03 +0900, Matt Lawrence matt@black-bart.net ha scritto::

Ok, I’ve been looking at Marshal, PStore, Madelaine and mnemonic. None of
them seem to provide the simple and transparent mechanism that I’m looking
for.

I’d like to be able to do something like:

arr = PersistantArray.use(“”)
hash = PersistentHash.use(“”)

Where is the name of the file to read and write data from and
the resulting object has all of the methods of Array or Hash and all
changes to the Array of Hash are automatically stored.

Matt_Lawrence · 25 April 2003 22:04

Well, it sounds a bit complex, but I can certainly wait. The big thing I
want is to be able to say something like ‘arr.push “foo”’ and it will be
persistant.

– Matt

···

On Fri, 25 Apr 2003, Ryan Pavlik wrote:

If you can hang on for a day or so, I’ll release Mephle on Monday.
I just added the ability to write non-networked apps a few nights ago,
along with a SQLite storage driver.

Matt_Lawrence · 25 April 2003 22:51

I suppose that this is a work for persistence/prevalence layers, but I
don’t think thay would actually save each change.

But it seem to me that working this way you’ll have too many atomic
writings, and you’ll loose in performance.

Not a problem with this application.

The Madeleine/prevayler approach should be to save the state of the
application space with predefined time slices, while the persistence
layer approach should be about using save/retrieve methods, so you’ll
just have to add a obj.save the way you’ll use Marshal(obj,io).

I don’t really want to save the application space.

Possibly this performance/fault_tolerance problem is the same of the
sync/async writing in filesystems, and a middle-way approach a-la
Madeleine could be , imho, a good thing

Not for these applications. Simple is very important. All I want to do
is to declare an object as persistant once and then have it ‘just work’.
Each of the programs I’m writing are only a few hundred lines long and I
want to keep them that short for maintainability reasons.

– Matt

···

On Sat, 26 Apr 2003, gabriele renzi wrote:

Anders_Bengtsson · 26 April 2003 12:21

gabriele renzi wrote:

I suppose that this is a work for persistence/prevalence layers, but I
don’t think thay would actually save each change.

But it seem to me that working this way you’ll have too many atomic
writings, and you’ll loose in performance.

The Madeleine/prevayler approach should be to save the state of the
application space with predefined time slices, while the persistence
layer approach should be about using save/retrieve methods, so you’ll
just have to add a obj.save the way you’ll use Marshal(obj,io).

These snapshots are an important feature, but not the central part of
Madeleine. Instead, the logs are the most important part.
You don’t log each change to every object, you log every command that
enters the system. If that command causes thousands of objects to be
changed, the only thing that is written is still just the command that
caused the changes.
So how much is written depends on the number of operations you do on the
system from the “outside”. For some applications this will cause lots of
atomic writes, for some very few.

Possibly this performance/fault_tolerance problem is the same of the
sync/async writing in filesystems, and a middle-way approach a-la
Madeleine could be , imho, a good thing

Madeleine uses fsync() when it writes to the filesystem, so no magic
middle-way there I’m afraid.
But if you don’t worry about loosing data you could comment that out and
have a much faster system.

/Anders

···

–

A n d e r s B e n g t s s o n | ndrsbngtssn@yahoo.se
Stockholm, Sweden |

Ara.T.Howard1 · 25 April 2003 23:05

none too fast - but this will do it:

~/eg/ruby > cat pobject.rb
require ‘pstore’

class PObject
DEFAULT_STORE = File.basename($0) << ‘.pstore’

attr :object

def initialize key, pstore = PStore.new (DEFAULT_STORE)
@key = key
@pstore = pstore
@object = nil

@pstore.transaction do
  @object = @pstore[@key] rescue nil
end

@object ||= yield

end

def method_missing (method, *args, &block)
@object.send (method, *args, &block)
persist
end

def persist
@pstore.transaction do
@pstore[@key] = @object
end
end
end

~/eg/ruby > cat pobjectdemo.rb
#!/usr/bin/env ruby

require ‘pobject’

a = PObject.new(:a) { Array.new }
a << Time.now

a.each do |time|
puts time
end

~/eg/ruby > pobjectdemo.rb
Fri Apr 25 22:48:37 GMT 2003

~/eg/ruby > pobjectdemo.rb
Fri Apr 25 22:48:37 GMT 2003
Fri Apr 25 22:48:39 GMT 2003

~/eg/ruby > pobjectdemo.rb
Fri Apr 25 22:48:37 GMT 2003
Fri Apr 25 22:48:39 GMT 2003
Fri Apr 25 22:48:40 GMT 2003

-a

···

On Sat, 26 Apr 2003, Matt Lawrence wrote:

On Fri, 25 Apr 2003, Ryan Pavlik wrote:

If you can hang on for a day or so, I’ll release Mephle on Monday.
I just added the ability to write non-networked apps a few nights ago,
along with a SQLite storage driver.

Well, it sounds a bit complex, but I can certainly wait. The big thing I
want is to be able to say something like ‘arr.push “foo”’ and it will be
persistant.

–

Ara Howard
NOAA Forecast Systems Laboratory
Information and Technology Services
Data Systems Group
R/FST 325 Broadway
Boulder, CO 80305-3328
Email: ara.t.howard@fsl.noaa.gov
Phone: 303-497-7238
Fax: 303-497-7259
====================================

Ara.T.Howard1 · 26 April 2003 00:25

Not a problem with this application.

I don’t really want to save the application space.

Not for these applications. Simple is very important. All I want to do is
to declare an object as persistant once and then have it ‘just work’. Each
of the programs I’m writing are only a few hundred lines long and I want to
keep them that short for maintainability reasons.

the code i posted does all of this nice and slowly, but also simply as you
desire. let me now if it works for you.

-a

···

On Sat, 26 Apr 2003, Matt Lawrence wrote:

–

Ara Howard
NOAA Forecast Systems Laboratory
Information and Technology Services
Data Systems Group
R/FST 325 Broadway
Boulder, CO 80305-3328
Email: ara.t.howard@fsl.noaa.gov
Phone: 303-497-7238
Fax: 303-497-7259
====================================

Ryan_Pavlik1 · 26 April 2003 05:21

It’s actually built to be easy. It’s somewhat sophisticated, but I
hate doing things manually the computer can do for me—so I try to
make things simple.

It will do exactly what you ask there:

arr  = Array.new_on(:vol)
arr << "foo"

And ‘arr’ magically persists. Of course, you’ll need some way to
retrieve it next time your program runs, but there are SQL indices
and the virtual path system to help there.

later,

···

On Sat, 26 Apr 2003 07:04:43 +0900 Matt Lawrence matt@black-bart.net wrote:

On Fri, 25 Apr 2003, Ryan Pavlik wrote:

If you can hang on for a day or so, I’ll release Mephle on Monday.
I just added the ability to write non-networked apps a few nights ago,
along with a SQLite storage driver.

Well, it sounds a bit complex, but I can certainly wait. The big thing I
want is to be able to say something like ‘arr.push “foo”’ and it will be
persistant.

–
Ryan Pavlik rpav@users.sf.net

“These monkeys of which you speak… are they mentally
deficient by human or monkey standards?” - 8BT

gabriele_renzi4 · 26 April 2003 14:47

well, in the FS metaphore I missed the fact that madeleine can be seen
as journaled

thanks

···

il Sat, 26 Apr 2003 21:21:41 +0900, Anders Bengtsson ndrsbngtssn@yahoo.se ha scritto::

Topic		Replies	Views
Doc Strings? ruby-talk	0	74	15 January 2003
Another RDoc niggle ruby-talk	1	70	28 January 2003
Stupid RDoc question ruby-talk	9	70	26 September 2003
Questions About Documenting erb.rb ruby-talk	6	110	27 October 2004
Using rdoc to document dynamically-generated classes ruby-talk	4	121	19 July 2004

[q]class documentation

this could be completely wrong

–

–

Related topics