Pliant talk forum

Pliant talk forum

Feature request: A search engine for finding built-in functions/methods

A much needed search engine for finding information regarding
Pliant's built-in functions/methods.
Message posted by maybe Marcus on 2002/05/19 22:09:04
When one is reengineering some third party Pliant code, it is sometimes quite
time consuming to find out what a particular function/method does. Specially
if one does know, or is not sure, of what is the datatype being handled by the
 function/method. In this case, the data type search engine is useless.

I and many other Pliant users/programmers would like to have a 
search engine for finding information regarding the usage of Pliant's built-in
functions/methods.
k
Message posted by maybe Hubert Tonneau on 2002/05/20 22:03:00
Seems hard to write.

On the other hand, with resonable efforts, we could build a tool that let you
click on a word in the source code, and would display all the metas and
functions implied to compile it, with pointers to the source for each of these.
Message posted by maybe Marcus on 2002/05/21 00:13:31
> On the other hand, with resonable efforts, we could build a tool that let you
> click on a word in the source code, and would display all the metas and
> functions implied to compile it, with pointers to the source for each of these.

This would be great! 

But to be really informative, the source code needs more documentation. 

While studying Pliant source code, one can spend many scrow-downs or page-turns
before bumping into the first commented function/method.

It would help a lot if at least those more popular functions/methods/metas were 
preceeded by a short comment giving some essential information about
- the semantics of the formal parameters
- what it does (as side effects)
- what it returns

To facilitate handling and understanding, this documentation should be
standardized.


Message posted by maybe Hubert Tonneau on 2002/05/21 08:27:56
> While studying Pliant source code, one can spend many scrow-downs or page-turns
> before bumping into the first commented function/method.

> It would help a lot if at least those more popular functions/methods/metas were 
> preceeded by a short comment giving some essential information about
> - the semantics of the formal parameters
> - what it does (as side effects)
> - what it returns

These should be external .page documentation files: putting many comments
in the source makes it harder to read.
Also, the source code has some constrains of it's own in Pliant (a function
used by another one will most of the time be defined first) and it's not
matching the logical way to explain the code.

Looking at other open project, I general find too much low level documentation
(line by line), and not enough high level information (describing the overall
structure and the relation between various peaces of the code).

I believe that comments in the code are mainly usefull to warn the reader when
there is a trick in the code.
Message posted by maybe Marcus on 2002/05/21 13:52:25
> Looking at other open project, I general find too much low level documentation
> (line by line), and not enough high level information (describing the overall
> structure and the relation between various peaces of the code).

Indeed.

After thinking a bit more about these difficulties my students (and myself) have
had trying to determine what a particular function/method/meta (let me call them
'procedure') is doing, I think what we need is to figure out which would be the 
best way to provide this information to the user using the tools we currently 
have, and without inserting comments in the Pliant code.

If we consider the case of someone trying to understand a piece of Pliant code,
it seems that finding the data types involved is easy. Then, once one knows the
data type, to find information about procedures that handle this data type, one
would have to use the data type search engine (SE), which currently lists (some
of )the methods that handle that type.

However, to make this really informative, we need the following to address:
- the SE needs to list _all_ the built in procedures that handle a particular
 type, e.g., 'parse' for the Str type
- for some of the procedures, the SE does not create a hyperlink to the place
in the source code where they are defined. It instead provides the location
where the procedure supposedly is located. But I have found that this location
is wrong, at least for some of them (I did not test many). E.g., the 'len'
procedure for the Str type. The SE says that its definition is in 
/pliant/language/basic/safe.pli, but  this path is incorrect.
- I am not sure the SE is working properly. E.g., for type Str, the first 
link in the "Cast to Str" table points to a weird place in the code...
- The SE should also provide a short description of what the procedure does. 
Where to store this, how to link this information to the data type, and
how to retrive this information... Huge '?'

- the SE should list _all_ procedures (functions+methods+meta) that handle a 
type

the data type search engine
a how-to page informing the user how to find information about a specific Pliant
procedure
Message posted by maybe Hubert Tonneau on 2002/05/21 14:07:47
The problem is that the location of all Pliant functions written in C is
wrong, because the C compiler will provide it only in the debugging informations
that cannot be accessed easily.
Also it should possible to correct this with reasonable efforts through
parsing the source code since the C part of Pliant is following very strict
syntax rules.
I have to think about that.
Message posted by maybe Marcus on 2002/05/21 14:38:26
Please ignore the last paragraph of my previous message. It's junk.
Message posted by maybe Marcus on 2002/05/21 15:14:34
Please ignore the last paragraph of my previous message. It's junk.
Message posted by maybe pom on 2002/05/22 06:33:44
The problem with the meta is more difficult. At the moment, meta have no
prototype at all, an the code of the meta itself checks the types of the arguments.

The addition of some syntax information for almost all the metas could allow
a listing by handled types.

Concerning the functions, it is more difficult to know what type they "mainly"
handle.

There are probably some data types "missing", because of their internal
equivalence with already known types. For instance:
FilePath (Str encoding a file path)
Access (Int encoding access for an argument)
etc.

The addition of new data types could ease a relevent sort of the methods
(a method working on argument access has still to be found looking at the
Int or uInt types)


Last, from my point of view, it is likely that soon or late, we will have
to add some "database" management of the links between code and documentation.
Update directives should then be embedded in both .pli and .page files.
Message posted by maybe Hubert Tonneau on 2002/05/22 07:18:01
> There are probably some data types "missing", because of their internal
> equivalence with already known types.

Any suggestion for defining these types through a single line.
Should they be just aliases, or create new instances of 'Type' then set
'maybe' automatically, or should they create new instances of 'Type' and
automatically generate casting functions.