Oleg N. Cher писал(а):
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.
Код: "OBERON"
MODULE Math; (** portable *)
(** Commonly needed Math for REALs. *)
(* And this is a local comment, not comes to interface. *)
IMPORT S := SYSTEM;
CONST
e* = 2.7182818284590452354E0;
pi* = 3.14159265358979323846E0;
Watson generates interface of the module:
Код: "OBERON"
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
https://zx.oberon.org