Re: [BLACKBOX] Export module's comments in BlackBox client interfaces (definitions)

From: [at]} <Marc>
Date: Fri, 25 Jan 2013 07:24:33 +0000

----boundary-LibPST-iamunique-501708870_-_-
Content-type: text/plain

Dear Oleg,

> Here is an useful idea for the BlackBox modules client interfaces that
> is shown if mark a module name and press Ctrl+D - the export comments.

This would be a nice feature indeed. While at ETH, I used it all the time.

Given our minimal resources for BlackBox related work, Oberon microsystems will not be able to put any energy in the design and implementation of such functionality, though. It is disappointing, I know, but things like this would need to be contributed by the community.

Thanks and kind regards,
Marc

> -----Original Message-----
> From: BlackBox [mailto:BLACKBOX{([at]})nowhere.xy
> Oleg N. Cher
> Sent: Donnerstag, 24. Januar 2013 16:51
> To: BLACKBOX{([at]})nowhere.xy
> Subject: [BLACKBOX] Export module's comments in BlackBox
> client interfaces (definitions)
>
> Dear Mr. Marc Frei, dear all,
>
> Here is an useful idea for the BlackBox modules client
> interfaces that
> is shown if mark a module name and press Ctrl+D - the export comments.
>
> In ETH Oberon's "Watson" tool there is implemented the feature of
> "exported comments". Please look here.
>
> ===============================
> =====> MODULE Math; (** portable *)
>
> (** Commonly needed Math for REALs.*)
>
> IMPORT S := SYSTEM;
>
> CONST e* = 2.7182818284590452354E0;
> pi* = 3.14159265358979323846E0;
> ===============================
> =====>
>
> Watson generates interface of the module:
>
> ===============================
> =====> DEFINITION Math; (* portable *)
>
> (*
> Commonly needed Math for REALs.
> *)
>
> CONST
> e = 2.7182818284590452354E0;
> pi = 3.14159265358979323846E0;
> ...
> END Math.
> ===============================
> =====>
> I don't know is this idea so good comes to be implemented in
> the current
> implementation of ".osf" format. But this important feature
> of classic
> ETH Oberon System need to be used. It's VERY useful to export
> comments
> to interface definitions, and I don't know even why it is not
> implemented in BlackBox.
>
> How can it be implemented? I think, needs to extend symbol
> files format
> by extra fields for put the exported comments there (they can be
> multi-line). And DevBrowser.ShowInterface needs to know about this
> fields and will be put the exported comments to the generated
> interface.
>
> Now a piece of book "The Oberon Companion: A Guide to Using and
> Programming Oberon System 3" (André L. Fischer, Hannes Marais) where
> this feature is described.
>
> ===============================
> =====> 3.7 Inspecting Module Definitions with Watson
>
> During software development, you will often need to refer to the
> definitions of modules delivered with the Oberon system. A definition
> module describes a module interface and is a summary of the complete
> module. It contains the declaration of the exported names
> which may be
> used by other modules. It is also known as the public view of
> the module
> and its advantage is its textual compactness. With this
> clearly defined
> module interface, a module can be used without knowledge of how it is
> implemented.
>
> In Oberon, it is not necessary to write down the definition of a
> module: Watson takes care of extracting the best information
> available
> about a specified module. For example, should the source text of a
> module be available, Watson can scan it for so-called
> exported comments
> which it presents to the user together with conventional module
> interface. An exported comment is a program comment starling with a
> double "*": (** .... *). The comment typically contains more
> information
> about how to use specific module features. As the source code of a
> module is sometimes not available to the user, Watson
> effectively goes
> in search of a previously generated definition file (with a .Def
> extension) first. Should both the definition file and the
> module source
> be missing, Watson searches for the module symbol file. If
> the latter is
> missing too, Watson tries to extract information about the
> module from
> its object file. In each step of the Watson search strategy,
> the amount
> of information Watson finds is diminished. Watson also has
> some further
> tricks up its sleeve. To reduce the clutter of many definition files,
> several definition files may be compressed and packed into a single
> archive file (with a .Arc extension). Watson can
> automatically extract
> and decompress definitions from such an archive file.
> ===============================
> =====>
> I hope, you will like this idea. This is a valuable feature, and I'm
> sure BlackBox users will accept the feature. Also I've
> already proposed
> to include this feature to GPCP.
>
>
> --
> Oleg N. Cher
> VEDAsoft Oberon Club
> http://zx.oberon2.ru
>
>
> ----
> To unsubscribe, send a message with body "SIGNOFF BLACKBOX"
> to LISTSERV{([at]})nowhere.xy
>

----
To unsubscribe, send a message with body "SIGNOFF BLACKBOX" to LISTSERV{([at]})nowhere.xy----boundary-LibPST-iamunique-501708870_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGZiaWRpcyBcZGVmZjB7XGZvbnR0YmwN
CntcZjBcZnN3aXNzXGZjaGFyc2V0MCBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7
fQ0Ke1xmMlxmbmlsXGZjaGFyc2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBD
b3VyaWVyIE5ldzt9fQ0Ke1xjb2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBc
Ymx1ZTI1NTt9DQpcdWMxXHBhcmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIERlYXIgT2xlZyxc
cGFyDQpccGFyDQo+IEhlcmUgaXMgYW4gdXNlZnVsIGlkZWEgZm9yIHRoZSBCbGFja0JveCBtb2R1
bGVzIGNsaWVudCBpbnRlcmZhY2VzIHRoYXQgXHBhcg0KPiBpcyBzaG93biBpZiBtYXJrIGEgbW9k
dWxlIG5hbWUgYW5kIHByZXNzIEN0cmwrRCAtIHRoZSBleHBvcnQgY29tbWVudHMuXHBhcg0KXHBh
cg0KVGhpcyB3b3VsZCBiZSBhIG5pY2UgZmVhdHVyZSBpbmRlZWQuIFdoaWxlIGF0IEVUSCwgSSB1
c2VkIGl0IGFsbCB0aGUgdGltZS5ccGFyDQpccGFyDQpHaXZlbiBvdXIgbWluaW1hbCByZXNvdXJj
ZXMgZm9yIEJsYWNrQm94IHJlbGF0ZWQgd29yaywgT2Jlcm9uIG1pY3Jvc3lzdGVtcyB3aWxsIG5v
dCBiZSBhYmxlIHRvIHB1dCBhbnkgZW5lcmd5IGluIHRoZSBkZXNpZ24gYW5kIGltcGxlbWVudGF0
aW9uIG9mIHN1Y2ggZnVuY3Rpb25hbGl0eSwgdGhvdWdoLiBJdCBpcyBkaXNhcHBvaW50aW5nLCBJ
IGtub3csIGJ1dCB0aGluZ3MgbGlrZSB0aGlzIHdvdWxkIG5lZWQgdG8gYmUgY29udHJpYnV0ZWQg
YnkgdGhlIGNvbW11bml0eS5ccGFyDQpccGFyDQpUaGFua3MgYW5kIGtpbmQgcmVnYXJkcyxccGFy
DQpNYXJjXHBhcg0KXHBhcg0KPiAtLS0tLU9yaWdpbmFsIE1lc3NhZ2UtLS0tLVxwYXINCj4gRnJv
bTogQmxhY2tCb3ggW21haWx0bzpCTEFDS0JPWEBMSVNUUy5PQkVST04uQ0hdIE9uIEJlaGFsZiBP
ZiBccGFyDQo+IE9sZWcgTi4gQ2hlclxwYXINCj4gU2VudDogRG9ubmVyc3RhZywgMjQuIEphbnVh
ciAyMDEzIDE2OjUxXHBhcg0KPiBUbzogQkxBQ0tCT1hATElTVFMuT0JFUk9OLkNIXHBhcg0KPiBT
dWJqZWN0OiBbQkxBQ0tCT1hdIEV4cG9ydCBtb2R1bGUncyBjb21tZW50cyBpbiBCbGFja0JveCBc
cGFyDQo+IGNsaWVudCBpbnRlcmZhY2VzIChkZWZpbml0aW9ucylccGFyDQo+IFxwYXINCj4gRGVh
ciBNci4gTWFyYyBGcmVpLCBkZWFyIGFsbCxccGFyDQo+IFxwYXINCj4gSGVyZSBpcyBhbiB1c2Vm
dWwgaWRlYSBmb3IgdGhlIEJsYWNrQm94IG1vZHVsZXMgY2xpZW50IFxwYXINCj4gaW50ZXJmYWNl
cyB0aGF0IFxwYXINCj4gaXMgc2hvd24gaWYgbWFyayBhIG1vZHVsZSBuYW1lIGFuZCBwcmVzcyBD
dHJsK0QgLSB0aGUgZXhwb3J0IGNvbW1lbnRzLlxwYXINCj4gXHBhcg0KPiBJbiBFVEggT2Jlcm9u
J3MgIldhdHNvbiIgdG9vbCB0aGVyZSBpcyBpbXBsZW1lbnRlZCB0aGUgZmVhdHVyZSBvZiBccGFy
DQo+ICJleHBvcnRlZCBjb21tZW50cyIuIFBsZWFzZSBsb29rIGhlcmUuXHBhcg0KPiBccGFyDQo+
ID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09XHBhcg0KPiA9PT09PT09PT09PVxwYXINCj4gTU9EVUxFIE1hdGg7ICAgICgqKiBwb3J0
YWJsZSAqKVxwYXINCj4gXHBhcg0KPiAoKiogICAgQ29tbW9ubHkgbmVlZGVkIE1hdGggZm9yIFJF
QUxzLiopXHBhcg0KPiBccGFyDQo+IElNUE9SVCBTIDo9IFNZU1RFTTtccGFyDQo+IFxwYXINCj4g
Q09OU1QgICAgZSogPSAyLjcxODI4MTgyODQ1OTA0NTIzNTRFMDtccGFyDQo+ICAgICAgcGkqID0g
My4xNDE1OTI2NTM1ODk3OTMyMzg0NkUwO1xwYXINCj4gPT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1ccGFyDQo+ID09PT09PT09PT09
XHBhcg0KPiBccGFyDQo+IFxwYXINCj4gV2F0c29uIGdlbmVyYXRlcyBpbnRlcmZhY2Ugb2YgdGhl
IG1vZHVsZTpccGFyDQo+IFxwYXINCj4gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09PT1ccGFyDQo+ID09PT09PT09PT09XHBhcg0KPiBE
RUZJTklUSU9OIE1hdGg7ICAgICgqIHBvcnRhYmxlICopXHBhcg0KPiBccGFyDQo+ICgqXHBhcg0K
PiAgICAgIENvbW1vbmx5IG5lZWRlZCBNYXRoIGZvciBSRUFMcy5ccGFyDQo+ICopXHBhcg0KPiBc
cGFyDQo+ICAgICAgQ09OU1RccGFyDQo+ICAgICAgICAgIGUgPSAyLjcxODI4MTgyODQ1OTA0NTIz
NTRFMDtccGFyDQo+ICAgICAgICAgIHBpID0gMy4xNDE1OTI2NTM1ODk3OTMyMzg0NkUwO1xwYXIN
Cj4gLi4uXHBhcg0KPiBFTkQgTWF0aC5ccGFyDQo+ID09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XHBhcg0KPiA9PT09PT09PT09PVxw
YXINCj4gXHBhcg0KPiBJIGRvbid0IGtub3cgaXMgdGhpcyBpZGVhIHNvIGdvb2QgY29tZXMgdG8g
YmUgaW1wbGVtZW50ZWQgaW4gXHBhcg0KPiB0aGUgY3VycmVudCBccGFyDQo+IGltcGxlbWVudGF0
aW9uIG9mICIub3NmIiBmb3JtYXQuIEJ1dCB0aGlzIGltcG9ydGFudCBmZWF0dXJlIFxwYXINCj4g
b2YgY2xhc3NpYyBccGFyDQo+IEVUSCBPYmVyb24gU3lzdGVtIG5lZWQgdG8gYmUgdXNlZC4gSXQn
cyBWRVJZIHVzZWZ1bCB0byBleHBvcnQgXHBhcg0KPiBjb21tZW50cyBccGFyDQo+IHRvIGludGVy
ZmFjZSBkZWZpbml0aW9ucywgYW5kIEkgZG9uJ3Qga25vdyBldmVuIHdoeSBpdCBpcyBub3QgXHBh
cg0KPiBpbXBsZW1lbnRlZCBpbiBCbGFja0JveC5ccGFyDQo+IFxwYXINCj4gSG93IGNhbiBpdCBi
ZSBpbXBsZW1lbnRlZD8gSSB0aGluaywgbmVlZHMgdG8gZXh0ZW5kIHN5bWJvbCBccGFyDQo+IGZp
bGVzIGZvcm1hdCBccGFyDQo+IGJ5IGV4dHJhIGZpZWxkcyBmb3IgcHV0IHRoZSBleHBvcnRlZCBj
b21tZW50cyB0aGVyZSAodGhleSBjYW4gYmUgXHBhcg0KPiBtdWx0aS1saW5lKS4gQW5kIERldkJy
b3dzZXIuU2hvd0ludGVyZmFjZSBuZWVkcyB0byBrbm93IGFib3V0IHRoaXMgXHBhcg0KPiBmaWVs
ZHMgYW5kIHdpbGwgYmUgcHV0IHRoZSBleHBvcnRlZCBjb21tZW50cyB0byB0aGUgZ2VuZXJhdGVk
IFxwYXINCj4gaW50ZXJmYWNlLlxwYXINCj4gXHBhcg0KPiBOb3cgYSBwaWVjZSBvZiBib29rICJU
aGUgT2Jlcm9uIENvbXBhbmlvbjogQSBHdWlkZSB0byBVc2luZyBhbmQgXHBhcg0KPiBQcm9ncmFt
bWluZyBPYmVyb24gU3lzdGVtIDMiIChBbmRyXCdlOSBMLiBGaXNjaGVyLCBIYW5uZXMgTWFyYWlz
KSB3aGVyZSBccGFyDQo+IHRoaXMgZmVhdHVyZSBpcyBkZXNjcmliZWQuXHBhcg0KPiBccGFyDQo+
ID09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09XHBhcg0KPiA9PT09PT09PT09PVxwYXINCj4gMy43ICAgSW5zcGVjdGluZyBNb2R1bGUg
RGVmaW5pdGlvbnMgd2l0aCBXYXRzb25ccGFyDQo+IFxwYXINCj4gICAgICBEdXJpbmcgc29mdHdh
cmUgZGV2ZWxvcG1lbnQsIHlvdSB3aWxsIG9mdGVuIG5lZWQgdG8gcmVmZXIgdG8gdGhlIFxwYXIN
Cj4gZGVmaW5pdGlvbnMgb2YgbW9kdWxlcyBkZWxpdmVyZWQgd2l0aCB0aGUgT2Jlcm9uIHN5c3Rl
bS4gQSBkZWZpbml0aW9uIFxwYXINCj4gbW9kdWxlIGRlc2NyaWJlcyBhIG1vZHVsZSBpbnRlcmZh
Y2UgYW5kIGlzIGEgc3VtbWFyeSBvZiB0aGUgY29tcGxldGUgXHBhcg0KPiBtb2R1bGUuIEl0IGNv
bnRhaW5zIHRoZSBkZWNsYXJhdGlvbiBvZiB0aGUgZXhwb3J0ZWQgbmFtZXMgXHBhcg0KPiB3aGlj
aCBtYXkgYmUgXHBhcg0KPiB1c2VkIGJ5IG90aGVyIG1vZHVsZXMuIEl0IGlzIGFsc28ga25vd24g
YXMgdGhlIHB1YmxpYyB2aWV3IG9mIFxwYXINCj4gdGhlIG1vZHVsZSBccGFyDQo+IGFuZCBpdHMg
YWR2YW50YWdlIGlzIGl0cyB0ZXh0dWFsIGNvbXBhY3RuZXNzLiBXaXRoIHRoaXMgXHBhcg0KPiBj
bGVhcmx5IGRlZmluZWQgXHBhcg0KPiBtb2R1bGUgaW50ZXJmYWNlLCBhIG1vZHVsZSBjYW4gYmUg
dXNlZCB3aXRob3V0IGtub3dsZWRnZSBvZiBob3cgaXQgaXMgXHBhcg0KPiBpbXBsZW1lbnRlZC5c
cGFyDQo+IFxwYXINCj4gICAgICBJbiBPYmVyb24sIGl0IGlzIG5vdCBuZWNlc3NhcnkgdG8gd3Jp
dGUgZG93biB0aGUgZGVmaW5pdGlvbiBvZiBhIFxwYXINCj4gbW9kdWxlOiBXYXRzb24gdGFrZXMg
Y2FyZSBvZiBleHRyYWN0aW5nIHRoZSBiZXN0IGluZm9ybWF0aW9uIFxwYXINCj4gYXZhaWxhYmxl
IFxwYXINCj4gYWJvdXQgYSBzcGVjaWZpZWQgbW9kdWxlLiBGb3IgZXhhbXBsZSwgc2hvdWxkIHRo
ZSBzb3VyY2UgdGV4dCBvZiBhIFxwYXINCj4gbW9kdWxlIGJlIGF2YWlsYWJsZSwgV2F0c29uIGNh
biBzY2FuIGl0IGZvciBzby1jYWxsZWQgXHBhcg0KPiBleHBvcnRlZCBjb21tZW50cyBccGFyDQo+
IHdoaWNoIGl0IHByZXNlbnRzIHRvIHRoZSB1c2VyIHRvZ2V0aGVyIHdpdGggY29udmVudGlvbmFs
IG1vZHVsZSBccGFyDQo+IGludGVyZmFjZS4gQW4gZXhwb3J0ZWQgY29tbWVudCBpcyBhIHByb2dy
YW0gY29tbWVudCBzdGFybGluZyB3aXRoIGEgXHBhcg0KPiBkb3VibGUgIioiOiAoKiogLi4uLiAq
KS4gVGhlIGNvbW1lbnQgdHlwaWNhbGx5IGNvbnRhaW5zIG1vcmUgXHBhcg0KPiBpbmZvcm1hdGlv
biBccGFyDQo+IGFib3V0IGhvdyB0byB1c2Ugc3BlY2lmaWMgbW9kdWxlIGZlYXR1cmVzLiBBcyB0
aGUgc291cmNlIGNvZGUgb2YgYSBccGFyDQo+IG1vZHVsZSBpcyBzb21ldGltZXMgbm90IGF2YWls
YWJsZSB0byB0aGUgdXNlciwgV2F0c29uIFxwYXINCj4gZWZmZWN0aXZlbHkgZ29lcyBccGFyDQo+
IGluIHNlYXJjaCBvZiBhIHByZXZpb3VzbHkgZ2VuZXJhdGVkIGRlZmluaXRpb24gZmlsZSAod2l0
aCBhIC5EZWYgXHBhcg0KPiBleHRlbnNpb24pIGZpcnN0LiBTaG91bGQgYm90aCB0aGUgZGVmaW5p
dGlvbiBmaWxlIGFuZCB0aGUgXHBhcg0KPiBtb2R1bGUgc291cmNlIFxwYXINCj4gYmUgbWlzc2lu
ZywgV2F0c29uIHNlYXJjaGVzIGZvciB0aGUgbW9kdWxlIHN5bWJvbCBmaWxlLiBJZiBccGFyDQo+
IHRoZSBsYXR0ZXIgaXMgXHBhcg0KPiBtaXNzaW5nIHRvbywgV2F0c29uIHRyaWVzIHRvIGV4dHJh
Y3QgaW5mb3JtYXRpb24gYWJvdXQgdGhlIFxwYXINCj4gbW9kdWxlIGZyb20gXHBhcg0KPiBpdHMg
b2JqZWN0IGZpbGUuIEluIGVhY2ggc3RlcCBvZiB0aGUgV2F0c29uIHNlYXJjaCBzdHJhdGVneSwg
XHBhcg0KPiB0aGUgYW1vdW50IFxwYXINCj4gb2YgaW5mb3JtYXRpb24gV2F0c29uIGZpbmRzIGlz
IGRpbWluaXNoZWQuIFdhdHNvbiBhbHNvIGhhcyBccGFyDQo+IHNvbWUgZnVydGhlciBccGFyDQo+
IHRyaWNrcyB1cCBpdHMgc2xlZXZlLiBUbyByZWR1Y2UgdGhlIGNsdXR0ZXIgb2YgbWFueSBkZWZp
bml0aW9uIGZpbGVzLCBccGFyDQo+IHNldmVyYWwgZGVmaW5pdGlvbiBmaWxlcyBtYXkgYmUgY29t
cHJlc3NlZCBhbmQgcGFja2VkIGludG8gYSBzaW5nbGUgXHBhcg0KPiBhcmNoaXZlIGZpbGUgKHdp
dGggYSAuQXJjIGV4dGVuc2lvbikuIFdhdHNvbiBjYW4gXHBhcg0KPiBhdXRvbWF0aWNhbGx5IGV4
dHJhY3QgXHBhcg0KPiBhbmQgZGVjb21wcmVzcyBkZWZpbml0aW9ucyBmcm9tIHN1Y2ggYW4gYXJj
aGl2ZSBmaWxlLlxwYXINCj4gPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT1ccGFyDQo+ID09PT09PT09PT09XHBhcg0KPiBccGFyDQo+
IEkgaG9wZSwgeW91IHdpbGwgbGlrZSB0aGlzIGlkZWEuIFRoaXMgaXMgYSB2YWx1YWJsZSBmZWF0
dXJlLCBhbmQgSSdtIFxwYXINCj4gc3VyZSBCbGFja0JveCB1c2VycyB3aWxsIGFjY2VwdCB0aGUg
ZmVhdHVyZS4gQWxzbyBJJ3ZlIFxwYXINCj4gYWxyZWFkeSBwcm9wb3NlZCBccGFyDQo+IHRvIGlu
Y2x1ZGUgdGhpcyBmZWF0dXJlIHRvIEdQQ1AuXHBhcg0KPiBccGFyDQo+IFxwYXINCj4gLS0gXHBh
cg0KPiBPbGVnIE4uIENoZXJccGFyDQo+IFZFREFzb2Z0IE9iZXJvbiBDbHViXHBhcg0KPiBodHRw
Oi8vengub2Jlcm9uMi5ydVxwYXINCj4gXHBhcg0KPiBccGFyDQo+IC0tLS1ccGFyDQo+IFRvIHVu
c3Vic2NyaWJlLCBzZW5kIGEgbWVzc2FnZSB3aXRoIGJvZHkgIlNJR05PRkYgQkxBQ0tCT1giIFxw
YXINCj4gdG8gTElTVFNFUlZATElTVFMuT0JFUk9OLkNIXHBhcg0KPiBccGFyDQpccGFyDQotLS0t
XHBhcg0KVG8gdW5zdWJzY3JpYmUsIHNlbmQgYSBtZXNzYWdlIHdpdGggYm9keSAiU0lHTk9GRiBC
TEFDS0JPWCIgdG8gTElTVFNFUlZATElTVFN9fQA9PT09PT09PT09PT09PQ=
----boundary-LibPST-iamunique-501708870_-_---

Received on Fri Jan 25 2013 - 08:24:33 UTC