Pliant talk forum

Pliant talk forum

Discussion: On the data type search engine

Message posted by maybe Marcus on 2002/06/15 21:31:15
I think it would be easier to understand the information returned by the engine
regarding the available methods, if the engine formatted the information as a 
function prototype, instead of as a table.

This would be more consistent with what we currently have in the documentation.
E.g., if the user queries the type List, then the engine would return (amongst 
other things):
.....
method l first -> c
   arg List l ; arg_C Arrow c
.....

Moreover, the engine should also inform which module the programmer needs to 
include in other to use the information.
Message posted by maybe Marcus on 2002/06/15 22:52:00
Again I will hit on the same key: we need to capitalize on this most valuable
tool developed by Patrice: the search engine.

My idea: Suppose I am maintaning a database of short textual descriptions 
of procedures, i.e., (meta)functions and methods. The entries are indexed 
by the name of the procedure. For instance, if a user types in "first", 
the engine returns: 

   Returns a pointer to the first value in the data set.
   If the data set is empty, the pointer will be null.

Which is the description currently available in the Pliant documentation.

Would it be possible to combine this database engine with the data type 
search engine, so that when the search engine lists the methods available for a 
type, it also provides access to the descriptions available in the database. 
E.g., the name of the procedure may appear as a hyperlink, which when cliked,
shows the description of the procedure.

Is this feasible?

What do you think?
Message posted by pom on 2002/06/16 09:38:17
> I think it would be easier to understand the information returned by the engine
 regarding the available methods, if the engine formatted the information as a 
 function prototype, instead of as a table.

Well, the problem is for functions with atypic prototypes or (int the futur)
meta with provided syntax. I don't know yet what is the better presentation.
Actually, we could have hard presentation in the difficult cases only...

> Moreover, the engine should also inform which module the programmer needs to 
 include.

Might have multiple choices... and this is not so easy to determine.
To help, I propose a small tool (Patch forum) to display submodule/module
dependency.

>The entries are indexed by the name of the procedure.

Not every methods with same name have the same semantic :-(
Actually, we would need a bit more because of overloading.
At least: # of arguments, type of first arg (if method or generic function)
If necessary (for ambiguity resolution): all the arg types, module and position.

> Is this feasible?
Sure it is, but I need some time to think a bit more about a general architecture.

Another possibility would be to make the type browser point to the relevant
documentation (wouldn't be much harder to do)
Message posted by maybe Marcus on 2002/06/17 18:48:11
I think we should let this issue of the documentation of Pliant's built in 
procedures simmer for awhile. There are still too many variables in the 
problem. I will move on and start reviewing/documenting other parts of the 
system.

Let me just insert "another variable" in this problem: Patrice has mentioned on
his last message that "Another possibility would be to make the type browser point to the relevant
 documentation (wouldn't be much harder to do)".

That would be interesting.

I was currently reviewing the link 'Data types', under 'Language constructs 
and Semantics'. 

Ideally, this static page would provide the same information provided by the 
dynamic pages created by the data type search engine, plus summarized 
explanations regarding all of Pliant's  types, built-in procedures, examples,
etc. Well, ideally.

Actually, its layout would consist of the same front page of the 
search engine. The difference being that when one presents a query or 
clicks on a data type, one sees a more verbose and complete information about
the respective type.

Therefore, it seems that sooner or later one will have to sit down, grab a 
triple expresso, start writing about *all* Pliant types, from
alpha to omega, using the search engine as a template. The first of the list
would be 'ActionRecord ' and the last 'uInt_hi'.

In this list, the only ones we have something written already are
Booleans  
Integers 
Floating Point Numbers 
Strings 
Enumerated 
Data Sets 





Message posted by maybe pom on 2002/06/19 07:52:14
Some others are also documented (but elsewhere...):
Expression, Argument, Type, Function

I don't know if we will have to write down all the documentation of all the
data types: some are only internal, private to one Module, some do not
need more documentation than the one that could be automaticaly provided.
For instance, when you know uInt is an unsigned integer, a list of available
methods, casts and operators might be sufficient.
Message posted by maybe Marcus on 2002/06/19 15:57:18
> Some others are also documented (but elsewhere...):
 > Expression, Argument, Type, Function

 I could find the first three, but couldn't find the documentation regarding
 the 'Function' data type.


 > I don't know if we will have to write down all the documentation of all the
 > data types

 You are right, that would be an overkill for the reader, and mostly for the 
 writer. But I think that the more 'relevant' data types should be more 
 thoroughly documented. By 'thoroughly documented' I mean, the data type rationale
 should be presented, all auxiliary functions should be listed, and a brief 
 description of their use and purpose as well. Then, once they are documented,
 the data type search Engine may provide links to this documentation.

 The list below, in my view, represents the 'relevant' data types. With the 
 exception of 'Functions', we have already lots of stuff  written. I will 
 review and structure it.

 Booleans  
 Integers 
 Floating Point Numbers 
 Strings 
 Enumerated
 Data Sets 
 Expressions
 Instructions
 Arguments
 Functions

 Do you think another 'relevant' type should be added to the list?
Message posted by pom on 2002/06/19 21:28:50
Here are some others (most are partly documented there and there)

Type
Module
All function related: Function, Meta, FunctionPrototype
Debug structures (ListingPosition, DebuggerInstructionRecord, TraceSlot, Logtrace, ...)
Code Generator related (GeneratorContext)
Error handling related (ErrorHandler ActionRecord ErrorId)
FileSystem related, File related, Database related
Time and date
Status, ExtendedStatus
Task related (ThreadHeader, Daemon, ...)
Parser related (Parser, ParserContext, ...)
Semaphores and signals

Application data types:

HTTP related (HtmlPage, ...)
User related (User, UserDatabase,...)
Forum related (Forum, ...)
etc.