Table of the public API methods

[euu2021]

Project: Table of the public API methods

1- What will be done: create a table with all the methods of the public API; short explanation and example for each method.

2- Why: Reason 1: explained here. Reason 2: explained here.

3- How:

3.1- Format:
See comments below.

3.2- What kind of information is on the table:
See comments below.

3.3- How to Contribute:
See comments below.

3.4- Some guidelines:

• make the examples as simple as possible;
• use groovy. See Scripts documentation #18 (reply in thread)

Things to consider and discuss:

• Maybe there should be multiple examples per method, like happens in the Autohotkey documentation?
• Is it useful to bring, also, more complex examples? I.e., take one real example from the scripts repository, and explain how the method is used there.
• If it was only intended for humans, I would probably create some maps to be referenced by the examples, because some scripts need context to make sense. Would it work to ChatGPT?
• Some methods are not very simple to make it work. In that case, there could be some kind of bookmarking to show that the contributor failed to create an example to that method.
• How to deal with deprecated methods?

---

Tasklist:

Doing:
Creating the examples.

Todo:

Done:
-define a first plan of action
-create a prototype for the table
First prototype, with only the first 2 categories of methods, at: https://github.com/euu2021/docs/blob/Table-of-API-methods/src/docs/scripting/API%20methods%20and%20examples

[EdoFro]

I like your idea.

Maybe some of it can be also added to the Java Doc in the API itself.

[euu2021]

Yes, let's see what works better with ChatGPT.

[dpolivaev]

I want to share my experience building Freeplane coding helper AI https://chat.openai.com/g/g-MAcfNdf8M-freeplane-script-helper.
At the moment I uploaded concatenated Java files containing API definitions with Javadoc and concatenated markdown files from this repo. I have also added to the configuration the instructions shown below.

I expect that if we have documentation like in order to get X, do Y, the GPT can learn and reason better because it can see the connection between the need and the solution.

This GPT is designed to assist with creating Groovy scripts and formulas specifically for Freeplane, an open-source software application for creating mind maps. It will provide guidance, suggestions, and troubleshooting tips for users seeking help with Freeplane's scripting and formula capabilities. The GPT will leverage its extensive knowledge of Groovy scripting language and Freeplane's API, focusing on offering practical solutions and best practices. It will avoid giving incorrect or misleading information and will not attempt to execute or test scripts directly. Instead, it will guide users in understanding and applying Freeplane's features effectively. The GPT will ask clarifying questions if necessary and adapt its explanations to the user's level of expertise. It will maintain a friendly and supportive tone, aiming to enhance the user's experience with Freeplane. It should always provide example scripts.

Every script is given the variables

"node"	having type "org.freeplane.api.Node" set to the currently selected node.
Here node.value gives access to the main content.
"c"	having type "org.freeplane.api.Controller" is a tool box for various tasks relating to the map or Freeplane altogether.

Mention only classes or methods mentioned in provided documentation.

Use groovy way to access getters and setters.

Take into account base type interfaces when available.

All relevant interfaces are provided in freeplane-api.txt
Verify all code examples and answers against this API documentation to ensure accuracy. It will avoid speculative or potentially incorrect information, prioritizing verified knowledge from the provided API source.
When possible  use groovy properties and operators instead of calling the methods in a Java way. If there are multiple ways to write code, prefer the shortest and most concise way. In short examples show all ways you know.

Consider org.freeplane.api.Convertible and its methods. For example it has no "toInteger", use num or num0.

[euu2021]

I will try to put 30 minutes a day on it. I don't know how long it will take to complete, though.

[euu2021]

Is it better to exclude the deprecated methods, or keep it? I think they will be useless for ChatGPT, right?

[dpolivaev]

Hello folks,

I am sorry for the delayed response. Only now I have a concrete idea of which kind of documentation I find the easiest to write and the most helpful. I would prefer having a single Groovy file containing a complete tutorial covering all API methods in a format looking like https://learnxinyminutes.com/docs/groovy/.

I think that it can even be a script that could be executed by Freeplane.
Also, if it is a Groovy file, you can use IDE to support writing it with auto-completion and to have all pieces of code checked and tested.

Once we have such a file we could easily feed it to ChatGPT and include it completely or partially in our documentation as described at https://rust-lang.github.io/mdBook/format/mdbook.html#including-files (as you know we use mdBook as our documentation renderer).

What do you think?
@euu2021 have you already started writing anything? I think that it would be easily transformed into the format I suggest.

Regards,
Dimitry

[dpolivaev]

It sounds like we could have two groovy files, one to explain the basics and another to cover all classes and methods.

[dpolivaev]

I have added new pages and groovy files to the repository.
You can find them at

• https://docs.freeplane.org/scripting/Basics.html
• https://docs.freeplane.org/scripting/Reference.html

The both pages have links that allow to easily edit the groovy files. They are places in the page footers and look as follows:

• For the Basics: Want to contribute? Edit the groovy file on github.
• For the Reference: Want to contribute? Edit the groovy file on github.

As doc project contributors you can click on the links and edit the files. When you commit, your changes are immediately deployed.

If non-contributors click on the links, their forks and branches are created automatically by GitHub.

[dpolivaev]

@EdoFro I have just sent you an invite to become the contributor.
@sifran-github You already have the access.

[dpolivaev]

@euu2021 You are invited too

[euu2021]

I like the idea of using the format from https://learnxinyminutes.com, for two reasons:

• working with tables in Markdown is a bit cumbersome;
• the https://learnxinyminutes.com format allows creating a kind of sequential narrative, which may work well with ChatGPT.

Anyway, little by little we can test different formats to see what works better.

[sifran-github]

In order to participate, do I have to do the following:

1. fork the entire repository into my user's repository (new repository every time?)
2. create a branch?
3. change the data
4. update my repository
5. send a pull request to the main repository

it seems complicated in order to just contribute a piece of small code.
is it the proper way? is there a simpler way? if not, is there a small guide on the proper way to do it? (I'm guessing that I missed something)

[sifran-github]

I understand the importance of pull requests when developing some complicated software. Even for a complicated docs changes. But this is an overkill for one document that is being contributed by small group of people... I actually thought about creating some google doc or something... just to avoid the complexity for one page... But if we can edit the files on the spot inside GitHub I think it can be good and quick.

I will soon try to contribute some small scripts as a start.

Thanks @dpolivaev

[dpolivaev]

How do you mean "some small scripts"? Currently, we have just 2 groovy files to fill with the content, and I suggest using https://learnxinyminutes.com/docs/groovy/ as an example.

[sifran-github]

I meant to add scripts and examples specifically for freeplane, so that chatgpt can learn how to program for freeplane.

Why do we need to build a groovy reference (just groovy language, without freeplane) if we can take some ready made groovy reference from the internet, like the link you provided?

I'm sorry if I ask questions that were answered somewhere.

[dpolivaev]

We do not need to write our own Groovy reference. I refer to https://learnxinyminutes.com/docs/groovy/ as an example of the way to write this kind of documentation, not as content.

[dpolivaev]

@sifran-github @EdoFro check https://chat.openai.com/share/d6a552b9-dbd4-4c07-bb0f-9d63bfe4294d

[euu2021]

My current situation is:

• I'm in the waitlist to get ChatGPT Plus. After they released the bot builder, there was a high demand and had to create this waitlist.
• While that, I'm filling a spreadsheet with examples of methods of two categories: Attributes and Clouds.

My plan was to make small scale tests with the bot builder, in order to define the best format for the table. I was thinking about giving the spreadsheet above to ChatGPT and then ask for a series of scripts using only those two categories of methods (Attributes and Clouds). If ChatGPT fails in creating a script, I would try to make adjustments in the format of the spreadsheet, and try again.

For example, I would like to test if ChatGPT understands better the example script in groovy style, or Java style. Maybe, the Java style will work better, because it is more similar to the abstract method, and doesn't rely on the concept of groovy properties. But, it's just my hypothesis.

Currently, my examples are oneliners, like this:

[dpolivaev]

ChatGPT can mimic our examples. Generally, it is equally familiar with Groovy and Java. And I prefer the Groovy way because it is more concise and I like it more than the old good Java.
And I think that for preparing the documentation we do not need to use ChatGPT. When the documentation is ready, it is on me to make it understand it.
Further, you do not need a subscription to see my example https://chat.openai.com/share/d6a552b9-dbd4-4c07-bb0f-9d63bfe4294d. You need it only to continue the conversation, but currently, it would be not very helpful because it lacks knowledge of Freeplane API as it learns from examples and we have not created them yet.

[dpolivaev]

The example just shows now tutorial could be written in the form of a groovy file.

[euu2021]

Ok. Let me see if I understood how the final form will look like. For example, the method findFirst​() from the interface AttributesRO, would be presented simply like this:

// returns the index of the first attribute with the name "aaa" if one exists or -1 otherwise

node.attributes.findFirst("aaa")

So, we can discard all the other information that is on the API HTML?

[dpolivaev]

Yes, for me it looks like the example is good and sufficient. It does not replace the javadoc. Actually, the java files are already available.

[euu2021]

I wrote a bit in the reference file. In order to get the format similar to https://learnxinyminutes.com/docs/groovy/, I suggest those guidelines:

The Classes in a sequence, following the sequence of the Interface Hierarchy, inside the API HTML -> Tree

Later, we can add a section on top, to introduce frequently used methods, as Edo suggested above.

Inside each Class, the methods:

Use #todo comments when you skip a class, a method or a description. Example:

Marking skipped classes or methods is important so we can know that we are not forgetting any methods.

Is it OK?

[dpolivaev]

I would track covered and not-covered methods not in the documentation but elsewhere because it is information about our internal development process that seems irrelevant to the reader. I would also not necessarily write the document in the order given in the javadoc because the order can be flexible and reflect which methods are likely to be used together or to have related purposes, even if they are defined for different interfaces.

[euu2021]

Ok, so my new suggestion to track covered methods is to use a google Sheets that anyone can Edit:

https://docs.google.com/spreadsheets/d/1Tu46HFFXR08oX0729rucm2nzIOBKRfWGasAo3DitIL8/edit?usp=sharing

It is simple:

I excluded deprecated methods.

Tomorrow I will add all the methods to that sheet.

[euu2021]

I added all the methods from the org.freeplane.api package.

I think I should not include the methods from the other packages, right?

[EdoFro]

We can add some lines in the comment with the structure of sample branchs to be used with the code examples.

In the Freeplane Stable Downloading folder in SourceForge is a text file with an "example of attributes to be pasted"

When you copy this text and paste it in Freeplane, it creates a branch with nodes with attributes.

its content:

+	attribute	12	
+	another attribute	text	
+	attribute name only		
			
node A			
+	attribute	26	
+	another attribute	abc	
+	attribute name only		
			
	child node B		
	+	attribute	84
	+	another attribute	xyz
	+	attribute name only	

So we can add lines like that to the groovy files to have some example branchs for the users. Not?

[euu2021]

For human users, this would be good, indeed. But, I wonder if GPT will understand it.

Also, I imagine that some of the methods will require this kind of context, in order to have meaningful examples. I still did not see methods that require it, but I will need a solution when I find one.

[dpolivaev]

I think ChatGPT would "understand" it. However, I wonder how it relates to scripting.

[EdoFro]

I did a sample here for the AttributesRO part.

It's intended for the users, not for ChatGPT

[euu2021]

I think it's good as a second layer of explanation. It will be cool to have the Reference guide growing over time in layers, each layer explaining from a different angle.

Now, don't you think that it makes more sense to place it after the script example?

So, it goes in this sequence:

• this is the example script
• and this is the result that you get when applying the example script to the sample

---

As a sidenote: looking at the example, I noticed that the method getKet() returns an exception if no attribute exists at the given index:

// Returns the attribute key at the index 1.
/*
    using "Sample Branch 01":
    selecting
        node "item A1" returns aaa
        node "item A2" returns exception: "org.freeplane.plugin.script.ExecuteScriptException: Array index out of range: 1, Array index out of range: 1"
        node "item A3" returns exception: "org.freeplane.plugin.script.ExecuteScriptException: Array index out of range: 1, Array index out of range: 1"
        node "item A4" returns bbb
 */
node.attributes.getKey(1)

Wouldn't it be more user-friendly if it returned "null"?

[sifran-github]

Added content: #140

[euu2021]

I created examples for most of the methods. I skipped some that gave me difficulties. The skipped methods are marked in the google sheet.

I'm eager to go on and make tests with ChatGPT (now, I have ChatGPT Plus). I will create another thread explaining how I plan to proceed with the tests.