@help directive

[Charles]

Cobra is a fine language, but I find it frustrating to have neither autocompletion nor integrated help when working with source code. As a stop-gap measure, I plan on implementing the @help directive described below. I think even with better IDE support, I would still use @help whose benefits go beyond autocompletion. And it may be possible that an IDE could leverage it when someone hits F1 in the code (perhaps after some refactoring).

A nice property of @help is that it is operating-system- and editor-neutral, so we'll all benefit.

Note that there are other compiler directives such as @ref and @number. They all start with "@" which is why "@help" does.

Here is the description:


@help is a Cobra directive to generate an HTML help file for a given expression, statement or declaration. The file is intended to give the developer:
* information about the topic in general
* interfaces to types
* a link to the Cobra wiki where appropriate
* a link to the specific type's documentation on the web, where determinable
* ready-made search links

Examples:

# the most typical use will be for expressions, especially objects and methods:
digest = @help hasher.computeHash(fs)
grid = @help GridView()

# additional uses:
@help print 10
@help assert x < y
@help def sum(x as int, y as int)

When the file is compiled with Cobra, the help file will be created and opened.

The syntax for @help is:

@help <expr>    
@help <statement>
@help <declaration>

Or simply:

@help <thing>

Note that @help <thing> passes <thing> through such that it is still compiled as part of the program. @help has the side effects of:

* writing an HTML help file for the given topic
* opening the HTML file in the default web browser
* outputting a warning

By default, the file is written to the current directory with the name "Help.TOPIC.html". You can change the behavior through environment variables. For example:

Code: Select all

COBRA_HELP_DIRECTORY=$HOME/Projects/Cobra/Help
COBRA_HELP_FILENAME=TOPIC.html
COBRA_HELP_OPEN=1


(In bash you might prefix these with "export" in a shell script. In Windows, it is "set".)

COBRA_HELP_OPEN can be set to a boolean value (true, 1, false or 0) or set to the path of a program to execute on the help file.

@help drastically reduces the time spent looking up information, especially API information.

You can also use @help to explore other people's code bases.

Although the help file will evolve as I implement this, ideas for content include:
* links in the footer and or header of the page to the Cobra web site
* the file name and line number where @help occurred
* the original source code
* for an expression, its type
* for an expression, the API in Cobra syntax for the type
* for a method or property invocation, the API in Cobra syntax of the receiving type
* a link to the Cobra site for any language element such as the print statement, the use directive, etc.
* for each type, a link to its exact documentation page, if determinable
** example: http://msdn.microsoft.com/en-us/library ... etime.aspx
* for a method or property, a link to its exact documentation page, if determinable
* for each type, search links for:
** msdn <type>
** .net <type>
** cobra language <type>
** C# <type>

... or something like that. I'll refine the search links as I go.

It will take some time to implement this. I'll probably start with expressions where this is most sorely needed (for the help on library types and their methods). When it's worth checking out, I'll announce here in the discussion forum.

Feedback is welcome.

[RIGHT_THEN]

hey Charles

So this @help directive is still after compilation.
let us take the Editor Senario. you say when a user would hit
F1 on say from a = 2 + 2 on "a" the help would be generated.
let it be something else even and consider "a" as just an example.

but to produce that help compiler will compile the whole programm first isn`t it?

Are you averse to XML? if this help thing produces info and stores it as XML also then
indeed it would be easy for Editors to parse it out. actually now dont be upset about it
but i was thinking if for every object in cobra compiler like AsExpr Stmt Box Node etc...
there was a ToXml() function just like we have ToString(). that would have been great for Tools.
but anyway you neednot loose sleep over it.

looking forward to this @help thing. yes such things are always good for languages and i dont
know any language that has this feature. it seems it can be expanded extensively and creatively.
even compiler errors can leverage this and point out to proper links and info for clarification.

Thanking_You
RIGHT_THEN

[Charles]

Correct, @help relies on the compiler so it can be used by anyone regardless of op sys or editor.

I'm not adverse to generating XML. But I was thinking that if the IDE/editor can embed a web browsing control, then it can just pop up what @help produces as a way to leverage @help with minimal effort.

Regarding XML, it could be generated through a visitor as well. You can find example visitors in the Cobra compiler under DocGenerator.cobra, CountNodesPhase.cobra and IdentifyMainPhase.cobra.

And yes, I think @help will be expanded over time in interesting ways.

[Charles]

This is ready for some testing. This is the test program I've been using:

class X

    def main
        s = 'aoeu'
        len = @help s.length
        @help s.replace('x', 'y')
        @help assert len > 0
        @help s
        trace len

Each @help creates an HTML file with:
* Location (method, class, file, line number)
* Type
* Receiver type (for "name.length" the type is int and the receiver type is String)
* Search links
* Config options

If you turn on the "show nodes" config option, you can also look at gory compiler details. For those you already hacking on the compiler, @help will be of extra use to you.

The API for the types is not yet there, but be assured I realize how important it is. You will still get value from the type info, method signature and/or the search links much of the time.

Please test it and report bugs and requests here in this thread. I'll knock them out or ticket them as we go.

How to install from source.

Thanks.

[Charles]

I have made numerous improvements to the @help output including the API for types, such as the properties and methods of whatever classes are related to what you asked for @help on. For example, @help on "someString.length" will give information about 3 types: String, int, char. The reasons why those are included for that example:

* "int" is the type returned by .length
* "String" is the receiver type in "someString.length"
* "char" is the "for loop type" or "inner type" of "String"

Now you can quickly see all the properties and methods available to you for any given type.

[RIGHT_THEN]

hey charles

today tested @help.
where are these enviornment variables to be set For Node details
i undestand by enviornment variables in windows the System wide variables
like Path etc.. do you mean that??

i did set COBRA_HELP_SHOW_NODES = true
Control Panel->All Control Panel Items->System->Advance System Settings->Advanced->Enviornment Variables
i dont see anything , it is just like before
i even tried @args

Thanking_You
RIGHT_THEN

[Charles]

If you set an env var via the GUI then you have to start up a new command line.

Or, in the same command line, you can use SET.

[RIGHT_THEN]

hey Charles

it is working after restarting my computer.which is strange
i am testing it in SD and not on CMD.
why did you opt to set them as Enviornment variables and not
programm specific. like @args

it could be

@help-args COBRA_HELP_SHOW_NODES = true

Thanking_You
RIGHT_THEN

[Charles]

Maybe just restarting SD would have worked too. But if it didn't, at least it was resolved.

I chose env vars because I didn't imagine that the settings were going to change much per person or project. Also, I find env vars easy to use, so it seemed like a reasonable approach.

In other news, I'll soon be adding the full method signatures which will make @help more useful. Enum members are needed as well.

[Charles]

There have been more improvements to @help:

-- Hover the mouse over a method or property to get its full signature.

-- Include inherited members in the list of members of a type.

-- Show members for nilable types.

-- Show members of enum types.

-- Better formatting.