Add Julia support

[josephsdavid]

Slowly figuring out how to add julia support, currently just for functions and structs as that is all i know how to do, but eventually maybe macro docs... todos:

• [x] struct documentation (much easier since there aren't 10 million types of arguments)
• [x] function documentation

[josephsdavid]

@danymat I believe this is good to be merged! As far as conventions go, I am still trying to figure out if/where any official guidelines exist, currently I am just following all the documentation examples I have seen so far!

[josephsdavid]

actually hold on that, after reading https://docs.julialang.org/en/v1/manual/documentation/ more thoroughly i have some changes

[josephsdavid]

I think for now this is probably sufficient but I will need to add more as I understand how julia documentation works!

[danymat]

Hello ! Very cool ! Can you share me some code examples of your features, and tell me which convention you used ?

[danymat]

Hello @josephsdavid , what's the state of the integration ?

[josephsdavid]

Oh! I have forgotten to finish the job here, let me make these things!

[josephsdavid]

So as far as conventions, Julia does not have established conventions like numpydoc jsdoc emmylua etc, so I guess we could just call it something like "Julia Alternative" or "Julia unspecified", it is based off of how we document open source stuff at my job, example, so I guess we could call it "Beacon format" for lack of a better name!

import Base: +, *, /

"""
    Point

A type representing a point in 2d space

Where...

    x::Number is the x coordinate
    y::Number is the y coordinate
"""
struct Point
    x::Number
    y::Number
end

# Open question: Generate docs for this type of function
+(a::Point, b::Point) =  Point(a.x + b.x, a.y + b.y)

+(a::Point, b::Number) = Point(a.x + b, a.y + b)

*(a::Point, b::Point) = Point(a.x * b.x, a.y * b.y)

/(a::Point, b::Number) = Point(a.x / b, a.y / b)



"""
    f(x,y,z,w)

f does some operations on some points and numbers

Where...

    z::Number is a shift factor, which shifts a point
    w::Number is a scaling factor, which scales the output
    x is the first point
    y is the second point
"""
function f(x, y, z::Number = 1, w::Number = 3)
    return (x * (y + z)) / w
end

above is a little code demo, two sort of open questions are:

1. how to document the f(x) = 2 * x syntax
2. Need to be able to grab the function title and arguments, currently this is done manually

[f3fora]

Actually Julia defines some conventions in the documentation or more accurately in Documenter.jl.

Arguments are actually introduced with:

"""
...
# Arguments
- `n::Integer`: the number of elements to compute.
- `dim::Integer=1`: the dimensions along which to perform the computation.
...
"""

[josephsdavid]

Actually Julia defines some conventions in the documentation or more accurately in Documenter.jl.

Arguments are actually introduced with:

"""
...
# Arguments
- `n::Integer`: the number of elements to compute.
- `dim::Integer=1`: the dimensions along which to perform the computation.
...
"""

Ah let me change this! Should be resolved in latest commit

[f3fora]

the format is currently wrong ("- \t%s::%s is $1") It should be "- %s::%s : $1"

[josephsdavid]

Here we go! Thank you by the way :)

[josephsdavid]

new code sample!

import Base: +, *, /

"""
    Point(x,y)

A struct representing a 2d point

# Arguments

- `x::Number` is the x coordinate
- `y::Number` is the y coordinate
"""
struct Point
    x::Number
    y::Number
end

# Open question: Generate docs for this type of function
+(a::Point, b::Point) =  Point(a.x + b.x, a.y + b.y)

+(a::Point, b::Number) = Point(a.x + b, a.y + b)

*(a::Point, b::Point) = Point(a.x * b.x, a.y * b.y)

/(a::Point, b::Number) = Point(a.x / b, a.y / b)



"""
    f(x,y,z,w)

f does some operations on some points and numbers

# Arguments

- `z::Number` is a shift factor, which shifts a point
- `w::Number` is a scaling factor, which scales the output
- `x` is the first point
- `y` is the second point
"""
function f(x, y, z::Number = 1, w::Number = 3)
    return (x * (y + z)) / w
end

a = Point(1,2)
b = Point(1,3)

f(a,b)

[f3fora]

According to the documentation:

• in struct each field can be documented independently with no need of adding arguments in the struct docstring.
• in arguments there is a : instead of is.

Moreover, the default argument value should be included and the arguments should be in order.

[josephsdavid]

According to the documentation:

• in struct each field can be documented independently with no need of adding arguments in the struct docstring.
• in arguments there is a : instead of is.

Moreover, the default argument value should be included and the arguments should be in order.

Thanks! I will knock this out after work :)

[josephsdavid]

So need to figure out how to get the arguments in order, it is tricky because I have to parse typed and nontyped arguments separately, and default arguments I need to figure out as well (and typed default arguments 🤯 !) So this will likely turn into a weekend project!

[danymat]

So need to figure out how to get the arguments in order, it is tricky because I have to parse typed and nontyped arguments separately, and default arguments I need to figure out as well

I'm afraid that's a limitation at the moment.. What's the state of the PR ?

[josephsdavid]

So need to figure out how to get the arguments in order, it is tricky because I have to parse typed and nontyped arguments separately, and default arguments I need to figure out as well

I'm afraid that's a limitation at the moment.. What's the state of the PR ?

if thats the limitation, it seems i just need to get the default arguments to show up and then it is good!

[josephsdavid]

So need to figure out how to get the arguments in order, it is tricky because I have to parse typed and nontyped arguments separately, and default arguments I need to figure out as well

I'm afraid that's a limitation at the moment.. What's the state of the PR ?

if thats the limitation, it seems i just need to get the default arguments to show up and then it is good!

Still stuck here lol but have not forgotten

[danymat]

Hello, what's the current state of this PR ? What are the current things I can catch on and try to merge it ?

[danymat]

Hello @josephsdavid, I can finish implementing this PR if you think it's in a good progress. If so, could you pinpoint me what needs to be continued ?

EDIT:

iirc, thats the only thing missing ?:

if thats the limitation, it seems i just need to get the default arguments to show up and then it is good!