MX2 MonkeyDoc

Community Forums/Monkey2 Talk/MX2 MonkeyDoc

Danilo(Posted 2016) [#1]
Looking at modules/std/databuffer.monkey2 for monkeydoc syntax.

For example:
#rem monkeydoc Writes a 64 bit double to the databuffer

In debug builds, a runtime error will occur if `offset` is outside the range of the databuffer.
	
#param offset The offset to write.
	
#end
Method PokeDouble( offset:Int,value:Double )

The #param line is completely ignored in the docs.

If we use @param it goes into the documentation, for example:
#rem monkeydoc Creates a databuffer with the contents of a file.
	
@param path The file path.
	
@return A new databuffer containing the contents of `path`, or null if `path` could not be opened.
	
#end
Function Load:DataBuffer( path:String )

The @param is in the docs, but @return is not.

What is the correct (future-proof) syntax for MonkeyDoc?


EDIT:
MonkeyDoc overview table
#Rem monkeydoc @hidden

    @hidden = Hides the doc, must appear first immediately after #rem monkeydoc

    This MonkeyDoc entry is ignored and not added to the output

#End



#Rem monkeydoc quick/short description (title)

    long description line 1

    long description line 2
    
    `Text is bold`              =  All text between ` and ` is bold.
    _Text is italics_           =  All text between _ and _ is italics.

    Lists:

    - Point 1
    - Point 2
    - Point 3


    Creating a table:

    | Header1           | Header2
    |:------------------|:-----------
    | Table Line 1      | Line 1
    | Table Line 2      | Line 2


    Important/Warning/Note:

    | `Warning:` |
    |:-----------|
    | Line 1<br> Line 2<br> Line 3


    # …                         =  Ignore line (monkeydoc comment)

    @param name description     =  Parameters

    @return description         =  Return type description

    @example                    =  Code example
     code
    @end

#End



'
' MonkeyDoc for overloaded functions/methods:
'
'    Overloaded variations are displayed all at the same help page.
'    Because of that, each overloaded function/method should have
'    different parameter names.
'    MonkeyDoc for ALL overloaded variations is written for the
'    very first overloaded variation only.
'
#Rem monkeydoc quick/short description (title)

    @param x Description for param 'x' of overload: F( x:Blah )

    @param y Description for param 'y' of overload: F( y:Int )

    @param a Description for param 'a' of overload: F( a:Int, b:Int )

    @param b Description for param 'b' of overload: F( a:Int, b:Int )

#End

Function F( x:Float )
    ' do something
End

Function F( y:Int )
    ' do something
End

Function F( a:Int, b:Int )
    ' do something
End



marksibly(Posted 2016) [#2]
> #param offset The offset to write.

This is my bad and I keep doing it! Should be '@param' of course.

Currently, the tags you can use are:

@param ident Description

@return Description - note actually output anywhere yet!

@hidden - hides the doc, must appear first immediately after #rem monkeydoc

The text immediately after #rem monkeydoc is 'quick help' and is what appears on the 'container' page for a doc.


Danilo(Posted 2016) [#3]
Thanks, Mark!

Updated table in 1st posting: Added BOLD text. If you tell me what is italic etc., I could add it quickly. ;)


marksibly(Posted 2016) [#4]
Italics is _blah_

It's pretty much 'standard' markdown (not that there's a standard...) so most of this should work:

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

One other thing to note: For better or worse (ie: I prefer this; others wont), I've decided to place all overloads for methods/functions on a single page. This basically means you have to stick all docs for an overloaded method/function in the first overload only, and modify the actual doc contents to reflect this.

So instead of:

#rem monkeydoc
...
@param x...

#end
Function F( x:Blah )
...
End

#rem monkeydoc
...
@param x...

#end
Function F( x:int )
...
End

...you need to go...

#rem monkeydoc

@param x

@param y - note: needed to rename 'x' param in second overload.

#end
Function F( x:Blah )
End

Function F( y:Int )
End
#end



marksibly(Posted 2016) [#5]
Oops, there's also:

@example

...example code...

@end

Currently, this just sticks the block in a <pre></pre> section but eventually it will produce a clickable example link.

Also, I need to handle 'indoc' links, probably via the old [[std.graphics.Pixmap]] format - which I should probably get onto today!


Danilo(Posted 2016) [#6]
Updated overview table in 1st posting, please check for correctness.


Danilo(Posted 2016) [#7]
Could it be that makedocs is broken?

It always creates docs for "modules/monkey.monkey2" only. Not for my own stuff, not for libc and std.


Shinkiro1(Posted 2016) [#8]
Will makedocs create documentation for functions, etc. if there is no comment block with monkeydoc above it?
It would be really useful to just get the simple declarations (for generating snippets for atom).


marksibly(Posted 2016) [#9]
It's working here.

If you don't specify any modules when using mx2cc makedocs, it reads the module list from modules/modules.txt (same as makemods). Otherwise, it should make the modules you specify, eg:

mx2cc_macos makedocs monkey libc std sdl2


produces this output here...

MX2CC V0.003

***** Doccing module 'monkey' *****

Parsing...
Semanting...

***** Doccing module 'libc' *****

Parsing...
Semanting...

***** Doccing module 'std' *****

Parsing...
Semanting...

***** Doccing module 'sdl2' *****

Parsing...
Semanting...


> Will makedocs create documentation for functions, etc. if there is no comment block with monkeydoc above it?

Yes, anything public/protected (but not private) will always be docced unless you use '#rem monkeydoc @hidden'.


Danilo(Posted 2016) [#10]
I get the same output, but only docs for module monkey are written to Disk.
Also added SFML to modules.txt without luck. Latest github version with MacOSX.


marksibly(Posted 2016) [#11]
Ok, my bad - just pushed a fix.


Danilo(Posted 2016) [#12]
Thanks, that works better for MX2 modules.

With my own monkeydocs I get:
***** Doccing module 'SFML' *****

Parsing...
Semanting...
libc++abi.dylib: terminating with uncaught exception of type bbException*
./makedocs.sh: line 4: 81325 Abort trap: 6           $mx2cc makedocs
Danilos-Mac-Pro:src danilo$



Danilo(Posted 2016) [#13]
OK, found it:
The exception above comes as soon as makedocs finds a extern class that „Extends Void“.

I guess it can’t find the class „Void“ for cross-referencing…


marksibly(Posted 2016) [#14]
Thanks - new version up that should fix this.


Danilo(Posted 2016) [#15]
Thanks, working fine now.

Noticed a minor formatting thingy: The description for the 'New' constructor is
somehow not in line with the other method descriptions. Just doesn't look 'perfect'. ;)

Example page:




Danilo(Posted 2016) [#16]
What's the MonkeyDoc tag for including an image? Which image formats are supported (png/jpg/gif/..)?

Can [[links]] have an alternate display-text? For example, [[namespace.Class]] is displayed as a link "Class",
but I would like to change the displayed text to the full namespace.Class - for example for "See also:" links.


Danilo(Posted 2016) [#17]
If not implemented yet, could the above two things be considered as feature requests? Including images in MonkeyDoc,
and specifying the link/display name for [[links]].


Danilo(Posted 2016) [#18]
I guess that's a NO...but thanks anyway! Including images in a help system is a basic requirement in my opinion,
because I want to show screenshots of gadgets/widgets for a GUI system.


Pharmhaus(Posted 2016) [#19]

I guess that's a NO...but thanks anyway! Including images in a help system is a basic requirement in my opinion,
because I want to show screenshots of gadgets/widgets for a GUI system.


+1


marksibly(Posted 2016) [#20]
I will be doing more work on the doc system in a while, but for now you can use an <img> tag, eg:

<img src="../../../../docs/img/monkey2-logo-63.png">

The 'doc base' for each doc page is "modules/blah/docs/__PAGES__/".

You can store images in the modules docs dir if you want, just don't store anything in the __PAGES__ dir as this gets rebuilt by makedocs. So you could put images in modules/blah/docs/img and reference them with:

<img src="../img/blah.png">