(unknown charset) [BLACKBOX] Export module's comments in BlackBox client interfaces (definitions)

From: (unknown charset) Oleg N. Cher <"Oleg>
Date: Thu, 24 Jan 2013 17:50:40 +0200

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

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----boundary-LibPST-iamunique-1107735694_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGZiaWRpcyBcZGVmZjB7XGZvbnR0YmwN
CntcZjBcZnN3aXNzXGZjaGFyc2V0MCBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7
fQ0Ke1xmMlxmbmlsXGZjaGFyc2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBD
b3VyaWVyIE5ldzt9fQ0Ke1xjb2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBc
Ymx1ZTI1NTt9DQpcdWMxXHBhcmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIERlYXIgTXIuIE1h
cmMgRnJlaSwgZGVhciBhbGwsXHBhcg0KXHBhcg0KSGVyZSBpcyBhbiB1c2VmdWwgaWRlYSBmb3Ig
dGhlIEJsYWNrQm94IG1vZHVsZXMgY2xpZW50IGludGVyZmFjZXMgdGhhdCBccGFyDQppcyBzaG93
biBpZiBtYXJrIGEgbW9kdWxlIG5hbWUgYW5kIHByZXNzIEN0cmwrRCAtIHRoZSBleHBvcnQgY29t
bWVudHMuXHBhcg0KXHBhcg0KSW4gRVRIIE9iZXJvbidzICJXYXRzb24iIHRvb2wgdGhlcmUgaXMg
aW1wbGVtZW50ZWQgdGhlIGZlYXR1cmUgb2YgXHBhcg0KXCc5M2V4cG9ydGVkIGNvbW1lbnRzXCc5
NC4gUGxlYXNlIGxvb2sgaGVyZS5ccGFyDQpccGFyDQo9PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XHBhcg0KTU9E
VUxFIE1hdGg7ICAgICgqKiBwb3J0YWJsZSAqKVxwYXINClxwYXINCigqKiAgICBDb21tb25seSBu
ZWVkZWQgTWF0aCBmb3IgUkVBTHMuKilccGFyDQpccGFyDQpJTVBPUlQgUyA6PSBTWVNURU07XHBh
cg0KXHBhcg0KQ09OU1QgICAgZSogPSAyLjcxODI4MTgyODQ1OTA0NTIzNTRFMDtccGFyDQogICAg
IHBpKiA9IDMuMTQxNTkyNjUzNTg5NzkzMjM4NDZFMDtccGFyDQo9PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09XHBh
cg0KXHBhcg0KXHBhcg0KV2F0c29uIGdlbmVyYXRlcyBpbnRlcmZhY2Ugb2YgdGhlIG1vZHVsZTpc
cGFyDQpccGFyDQo9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09XHBhcg0KREVGSU5JVElPTiBNYXRoOyAgICAoKiBw
b3J0YWJsZSAqKVxwYXINClxwYXINCigqXHBhcg0KICAgICBDb21tb25seSBuZWVkZWQgTWF0aCBm
b3IgUkVBTHMuXHBhcg0KKilccGFyDQpccGFyDQogICAgIENPTlNUXHBhcg0KICAgICAgICAgZSA9
IDIuNzE4MjgxODI4NDU5MDQ1MjM1NEUwO1xwYXINCiAgICAgICAgIHBpID0gMy4xNDE1OTI2NTM1
ODk3OTMyMzg0NkUwO1xwYXINCi4uLlxwYXINCkVORCBNYXRoLlxwYXINCj09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT1ccGFyDQpccGFyDQpJIGRvblwnOTJ0IGtub3cgaXMgdGhpcyBpZGVhIHNvIGdvb2QgY29tZXMg
dG8gYmUgaW1wbGVtZW50ZWQgaW4gdGhlIGN1cnJlbnQgXHBhcg0KaW1wbGVtZW50YXRpb24gb2Yg
Ii5vc2YiIGZvcm1hdC4gQnV0IHRoaXMgaW1wb3J0YW50IGZlYXR1cmUgb2YgY2xhc3NpYyBccGFy
DQpFVEggT2Jlcm9uIFN5c3RlbSBuZWVkIHRvIGJlIHVzZWQuIEl0XCc5MnMgVkVSWSB1c2VmdWwg
dG8gZXhwb3J0IGNvbW1lbnRzIFxwYXINCnRvIGludGVyZmFjZSBkZWZpbml0aW9ucywgYW5kIEkg
ZG9uXCc5MnQga25vdyBldmVuIHdoeSBpdCBpcyBub3QgXHBhcg0KaW1wbGVtZW50ZWQgaW4gQmxh
Y2tCb3guXHBhcg0KXHBhcg0KSG93IGNhbiBpdCBiZSBpbXBsZW1lbnRlZD8gSSB0aGluaywgbmVl
ZHMgdG8gZXh0ZW5kIHN5bWJvbCBmaWxlcyBmb3JtYXQgXHBhcg0KYnkgZXh0cmEgZmllbGRzIGZv
ciBwdXQgdGhlIGV4cG9ydGVkIGNvbW1lbnRzIHRoZXJlICh0aGV5IGNhbiBiZSBccGFyDQptdWx0
aS1saW5lKS4gQW5kIERldkJyb3dzZXIuU2hvd0ludGVyZmFjZSBuZWVkcyB0byBrbm93IGFib3V0
IHRoaXMgXHBhcg0KZmllbGRzIGFuZCB3aWxsIGJlIHB1dCB0aGUgZXhwb3J0ZWQgY29tbWVudHMg
dG8gdGhlIGdlbmVyYXRlZCBpbnRlcmZhY2UuXHBhcg0KXHBhcg0KTm93IGEgcGllY2Ugb2YgYm9v
ayAiVGhlIE9iZXJvbiBDb21wYW5pb246IEEgR3VpZGUgdG8gVXNpbmcgYW5kIFxwYXINClByb2dy
YW1taW5nIE9iZXJvbiBTeXN0ZW0gMyIgKEFuZHJcJ2U5IEwuIEZpc2NoZXIsIEhhbm5lcyBNYXJh
aXMpIHdoZXJlIFxwYXINCnRoaXMgZmVhdHVyZSBpcyBkZXNjcmliZWQuXHBhcg0KXHBhcg0KPT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PVxwYXINCjMuNyAgIEluc3BlY3RpbmcgTW9kdWxlIERlZmluaXRpb25zIHdp
dGggV2F0c29uXHBhcg0KXHBhcg0KICAgICBEdXJpbmcgc29mdHdhcmUgZGV2ZWxvcG1lbnQsIHlv
dSB3aWxsIG9mdGVuIG5lZWQgdG8gcmVmZXIgdG8gdGhlIFxwYXINCmRlZmluaXRpb25zIG9mIG1v
ZHVsZXMgZGVsaXZlcmVkIHdpdGggdGhlIE9iZXJvbiBzeXN0ZW0uIEEgZGVmaW5pdGlvbiBccGFy
DQptb2R1bGUgZGVzY3JpYmVzIGEgbW9kdWxlIGludGVyZmFjZSBhbmQgaXMgYSBzdW1tYXJ5IG9m
IHRoZSBjb21wbGV0ZSBccGFyDQptb2R1bGUuIEl0IGNvbnRhaW5zIHRoZSBkZWNsYXJhdGlvbiBv
ZiB0aGUgZXhwb3J0ZWQgbmFtZXMgd2hpY2ggbWF5IGJlIFxwYXINCnVzZWQgYnkgb3RoZXIgbW9k
dWxlcy4gSXQgaXMgYWxzbyBrbm93biBhcyB0aGUgcHVibGljIHZpZXcgb2YgdGhlIG1vZHVsZSBc
cGFyDQphbmQgaXRzIGFkdmFudGFnZSBpcyBpdHMgdGV4dHVhbCBjb21wYWN0bmVzcy4gV2l0aCB0
aGlzIGNsZWFybHkgZGVmaW5lZCBccGFyDQptb2R1bGUgaW50ZXJmYWNlLCBhIG1vZHVsZSBjYW4g
YmUgdXNlZCB3aXRob3V0IGtub3dsZWRnZSBvZiBob3cgaXQgaXMgXHBhcg0KaW1wbGVtZW50ZWQu
XHBhcg0KXHBhcg0KICAgICBJbiBPYmVyb24sIGl0IGlzIG5vdCBuZWNlc3NhcnkgdG8gd3JpdGUg
ZG93biB0aGUgZGVmaW5pdGlvbiBvZiBhIFxwYXINCm1vZHVsZTogV2F0c29uIHRha2VzIGNhcmUg
b2YgZXh0cmFjdGluZyB0aGUgYmVzdCBpbmZvcm1hdGlvbiBhdmFpbGFibGUgXHBhcg0KYWJvdXQg
YSBzcGVjaWZpZWQgbW9kdWxlLiBGb3IgZXhhbXBsZSwgc2hvdWxkIHRoZSBzb3VyY2UgdGV4dCBv
ZiBhIFxwYXINCm1vZHVsZSBiZSBhdmFpbGFibGUsIFdhdHNvbiBjYW4gc2NhbiBpdCBmb3Igc28t
Y2FsbGVkIGV4cG9ydGVkIGNvbW1lbnRzIFxwYXINCndoaWNoIGl0IHByZXNlbnRzIHRvIHRoZSB1
c2VyIHRvZ2V0aGVyIHdpdGggY29udmVudGlvbmFsIG1vZHVsZSBccGFyDQppbnRlcmZhY2UuIEFu
IGV4cG9ydGVkIGNvbW1lbnQgaXMgYSBwcm9ncmFtIGNvbW1lbnQgc3Rhcmxpbmcgd2l0aCBhIFxw
YXINCmRvdWJsZSAiKiI6ICgqKiAuLi4uICopLiBUaGUgY29tbWVudCB0eXBpY2FsbHkgY29udGFp
bnMgbW9yZSBpbmZvcm1hdGlvbiBccGFyDQphYm91dCBob3cgdG8gdXNlIHNwZWNpZmljIG1vZHVs
ZSBmZWF0dXJlcy4gQXMgdGhlIHNvdXJjZSBjb2RlIG9mIGEgXHBhcg0KbW9kdWxlIGlzIHNvbWV0
aW1lcyBub3QgYXZhaWxhYmxlIHRvIHRoZSB1c2VyLCBXYXRzb24gZWZmZWN0aXZlbHkgZ29lcyBc
cGFyDQppbiBzZWFyY2ggb2YgYSBwcmV2aW91c2x5IGdlbmVyYXRlZCBkZWZpbml0aW9uIGZpbGUg
KHdpdGggYSAuRGVmIFxwYXINCmV4dGVuc2lvbikgZmlyc3QuIFNob3VsZCBib3RoIHRoZSBkZWZp
bml0aW9uIGZpbGUgYW5kIHRoZSBtb2R1bGUgc291cmNlIFxwYXINCmJlIG1pc3NpbmcsIFdhdHNv
biBzZWFyY2hlcyBmb3IgdGhlIG1vZHVsZSBzeW1ib2wgZmlsZS4gSWYgdGhlIGxhdHRlciBpcyBc
cGFyDQptaXNzaW5nIHRvbywgV2F0c29uIHRyaWVzIHRvIGV4dHJhY3QgaW5mb3JtYXRpb24gYWJv
dXQgdGhlIG1vZHVsZSBmcm9tIFxwYXINCml0cyBvYmplY3QgZmlsZS4gSW4gZWFjaCBzdGVwIG9m
IHRoZSBXYXRzb24gc2VhcmNoIHN0cmF0ZWd5LCB0aGUgYW1vdW50IFxwYXINCm9mIGluZm9ybWF0
aW9uIFdhdHNvbiBmaW5kcyBpcyBkaW1pbmlzaGVkLiBXYXRzb24gYWxzbyBoYXMgc29tZSBmdXJ0
aGVyIFxwYXINCnRyaWNrcyB1cCBpdHMgc2xlZXZlLiBUbyByZWR1Y2UgdGhlIGNsdXR0ZXIgb2Yg
bWFueSBkZWZpbml0aW9uIGZpbGVzLCBccGFyDQpzZXZlcmFsIGRlZmluaXRpb24gZmlsZXMgbWF5
IGJlIGNvbXByZXNzZWQgYW5kIHBhY2tlZCBpbnRvIGEgc2luZ2xlIFxwYXINCmFyY2hpdmUgZmls
ZSAod2l0aCBhIC5BcmMgZXh0ZW5zaW9uKS4gV2F0c29uIGNhbiBhdXRvbWF0aWNhbGx5IGV4dHJh
Y3QgXHBhcg0KYW5kIGRlY29tcHJlc3MgZGVmaW5pdGlvbnMgZnJvbSBzdWNoIGFuIGFyY2hpdmUg
ZmlsZS5ccGFyDQo9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09
PT09PT09PT09PT09PT09PT09PT09PT09PT09XHBhcg0KXHBhcg0KSSBob3BlLCB5b3Ugd2lsbCBs
aWtlIHRoaXMgaWRlYS4gVGhpcyBpcyBhIHZhbHVhYmxlIGZlYXR1cmUsIGFuZCBJJ20gXHBhcg0K
c3VyZSBCbGFja0JveCB1c2VycyB3aWxsIGFjY2VwdCB0aGUgZmVhdHVyZS4gQWxzbyBJJ3ZlIGFs
cmVhZHkgcHJvcG9zZWQgXHBhcg0KdG8gaW5jbHVkZSB0aGlzIGZlYXR1cmUgdG8gR1BDUC5ccGFy
DQpccGFyDQpccGFyDQotLSBccGFyDQpPbGVnIE4uIENoZXJccGFyDQpWRURBc29mdCBPYmVyb24g
Q2x1YlxwYXINCmh0dHA6Ly96eC5vYmVyb24yLnJ1XHBhcg0KXHBhcg0KXHBhcg0KLS0tLVxwYXIN
ClRvIHVuc3Vic2NyaWJlLCBzZW5kIGEgbWVzc2FnZSB3aXRoIGJvZHkgIlNJR05PRkYgQkxBQ0tC
T1giIHRvIExJU1RTRVJWQExJU1RTLk9CRVJPTi5DSFxwYXINCn0=
----boundary-LibPST-iamunique-1107735694_-_---

Received on Thu Jan 24 2013 - 16:50:40 UTC