MX2 MonkeyDoc
Community Forums/Monkey2 Talk/MX2 MonkeyDoc
| ||
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 |
| ||
> #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. |
| ||
Thanks, Mark! Updated table in 1st posting: Added BOLD text. If you tell me what is italic etc., I could add it quickly. ;) |
| ||
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 |
| ||
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! |
| ||
Updated overview table in 1st posting, please check for correctness. |
| ||
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. |
| ||
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). |
| ||
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'. |
| ||
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. |
| ||
Ok, my bad - just pushed a fix. |
| ||
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$ |
| ||
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… |
| ||
Thanks - new version up that should fix this. |
| ||
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: ![]() |
| ||
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. |
| ||
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]]. |
| ||
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. |
| ||
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 |
| ||
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"> |