current status of documentation

[DaddyWesker]

Subj

get-doc/help! for empty doesn't work just like for =.
For empty help! gives

Function empty (type (-> %Undefined%)) No documentation
[()]

For =:

Function = (type (-> $t#48 $t#48 Atom)) No documentation
[()]

Another problem is duplicating functions. There are several of them. I've tried to create some documentation which aggregate both variants but I wasn't been able to do it for every function. For example, @param. It uses two type notations. In the second one @param have two inputs but I don't get which ones. Same goes to @return.

Since currently documentation is duplicating for such functions even if there is only one documentation I'm currently commenting documentation for those funcs.

For some unknown to me reason, same problem doesn't occur for @doc-formal though it has two type notations as well.

help! also doesn't show anything for (@kind function) and (@kind atom).

[DaddyWesker]

@vsbogd
There are two types of problems. First, for some reason get-doc/help for some reason returns "No documentation" for some functions. Second, for &self metta hangs for some time and then segmentation fault. I've tried to understand what is a reason behind this. For the second problem, segmentation fault could be triggered using such code:

!(let $top-space (mod-space! top)
    (unify $top-space (@doc &self $desc (@params $params) $ret)
        $ret
        Err))

So segmentation fault happening on this step. Unfortunately, I don't know why.

As for the first problem, it is somewhat tricky. For example, two functions: xor and or. Both have two input parameters and output. Here is docs:

(@doc or
  (@desc "Logical disjunction of two arguments")
  (@params (
    (@param "First argument")
    (@param "Second argument")))
  (@return "True if any of input arguments is True, False - otherwise"))
 
(@doc xor
  (@desc "Exclusive disjunction of two arguments")
  (@params (
    (@param "First argument")
    (@param "Second argument")))
  (@return "Return values are the same as logical disjunction, but when both arguments are True xor will return False"))

So, those docs are kinda similar, but !(help! xor) gives:

Function xor: (-> Bool Bool Bool) Exclusive disjunction of two arguments
Parameters:
  (type Bool) First argument
  (type Bool) Second argument
Return: (type Bool) Return values are the same as logical disjunction, but when both arguments are True xor will return False
[()]

and !(help! or) gives:

Function or (type (-> Bool Bool Bool)) No documentation
[()]

I don't get it. If I'll use this code once again

!(let $top-space (mod-space! top)
    (unify $top-space (@doc or $desc (@params $params) $ret)
        $ret
        Err))

I'll get Err. So for some reason unify doesn't work for or.

Moreover, if I'll add doc for or inside script I'm launching, everything will be fine. Unfortunately, I don't know inner structure of metta so I can't understand what is happening here.

[vsbogd]

Suggested change

	; TODO: get-doc not showing docs for following two functions (@kind function) and (@kind atom) for some reason.
	(@doc (@kind function)
	(@desc "Used for documentation purposes. Shows type of entity to be documented. (@kind function) in this case")
	(@return "(@kind function) entity"))
	(@doc (@kind function)
	(@desc "Used for documentation purposes. Shows type of entity to be documented. (@kind function) in this case"))

[DaddyWesker]

@vsbogd
For some reason in minimal metta for (@kind function ) documentation returned two times:

Atom (@kind function): (%Undefined% (-> Atom Atom)) Used for documentation purposes. Shows type of entity to be documented. (@kind function) in this case
Atom (@kind function): DocKindFunction Used for documentation purposes. Shows type of entity to be documented. (@kind function) in this case
[(), ()]

In regular metta everything is fine. Also, @kind atom works fine in both metta.

[vsbogd]

@luketpeterson I would like to check it with you. Analysis shows that it doesn't work because when this module is loaded or token is replaced by Rust implementation. But when user executes !(help or) or is replaced by the Python implementation it is the reason why documentation is not returned (Python and Rust implementations do not match).

In MettaMod code I see the following snippet:

hyperon-experimental/lib/src/metta/runner/modules/mod.rs

Lines 96 to 100 in 5ab9f11

	if !no_stdlib {
	if let Some(stdlib_mod_id) = metta.0.stdlib_mod.get() {
	new_mod.import_all_from_dependency(*stdlib_mod_id, metta.get_mod_ptr(*stdlib_mod_id)).unwrap();
	}
	}

To me it sounds like one one implementation of the stdlib tokens should be loaded: either Rust or Python but looks like in fact we have two of them at the same time. Is it made by intention or it is a bug?

[vsbogd]

If it is a bug and we can fix it then it could fix the documentation behaviour. On the other hand this operation duality can mean that we need separate documentation for Rust grounded atoms and Python grounded atoms.

[luketpeterson]

To me it sounds like one one implementation of the stdlib tokens should be loaded

The python stdlib could be changed to not load corelib, but that's not what it currently does. Right now it loads corelib (which is the Rust stdlib), and overwrites / supersedes certain definitions from corelib with its own definitions.

But I feel like this docs issue is only tangentially related to that question.

My first thought is: If the Python hyperon/stdlib.py is providing alternative versions of these operation atoms, it should also be responsible to provide documentation for them.

But my second thought is: Since the changes made a few months ago make the type conversion for grounded atoms much more flexible and add powerful arithmetic & logic ops to corelib, can we get rid of these op atoms in hyperon/stdlib.py altogether? Although certainly in a different PR from this one?

[vsbogd]

Yeah, to me these last two changes you are talking about are also a orthogonal to each other.

One question is about documentation and here I am starting to think that it is more logical to have documentation for the grounded atom inside its implementation like we having grounded atom's type. Thus this documentation is always available from the atom itself. It contradicts to the way I wanted to see grounded atoms in future (I mean for the grounded function I would like to represent both types and docs inside atomspace and keep only function implementation as a native code) but on the other hand it is better to have internally aligned representation and switch to another one in one step.

Second question is should we have duplicates of the operations in Python stdlib. The idea was to keep Python stdlib working with native data in a native way. Taking into account calling Python method anyway requires cloning vales I doubt implementing operations on numbers and boolean values in Python makes much sense . Thus may be we could get rid of duplicates in Python (Strings serialization is still not implemented thus we cannot fully remove duplicates at the moment probably)

[vsbogd]

@DaddyWesker could you please also add docs for operations added by #698 and here https://github.com/trueagi-io/hyperon-experimental/pull/691/files#diff-0cc50ef2951a3babcc599e443e489112ae31c6f8e76da2d22b97160ad85d9a32

[DaddyWesker]

@DaddyWesker could you please also add docs for operations added by #698 and here https://github.com/trueagi-io/hyperon-experimental/pull/691/files#diff-0cc50ef2951a3babcc599e443e489112ae31c6f8e76da2d22b97160ad85d9a32

Probably done. Please check.

[vsbogd]

@DaddyWesker please merge my review comments in DaddyWesker#3