How to create a help file of a module?

Started by Midimaster, May 05, 2021, 12:08:09

Previous topic - Next topic

Midimaster

I'm planning to convert my MiniAudioWrapper to a module. But I want to add the comfort of a detailed help file as we can see it in a lot of modules.

I already learned that adding bbdoc-lines to the BMX-code will create a help page.
Code (BlitzMax) Select
SuperStrict

Rem
bbdoc: MiniAudioWrapper
End Rem
Module MM.MiniAudio
ModuleInfo "Version: 1.10"
ModuleInfo "License: MIT"
ModuleInfo "Copyright: David Reid - mackron@gmail.com  https://miniaud.io"
ModuleInfo "Copyright: Wrapper Peter Wolkersdorfer thanks To col from https://github.com/davecamp"
ModuleInfo "Modserver: BRL"

ModuleInfo "History: 1.10"
ModuleInfo "History: Add MP3-Load"

Import BRL.StandardIO
Import BRL.audiosample
Import "MiniAudioWrapper.c"

Rem
bbdoc: MiniAudio-Wrapper.
about: Use MiniAudio as a Callback Audio device.
End Rem


Type TMiniAudio
'DeviceTyp:
Const PLAYBACK:Int=1, CAPTURE:Int=2, DUPLEX:Int=3, LOOPBACK:Int=4
'Format:
Const FORMAT_U8:Int=1, FORMAT_S16:Int=2 ,FORMAT_S24:Int=3, FORMAT_S32:Int=4, FORMAT_F32:Int=5
Const SUCCESS:Int=0;

Field  DeviceConfig: Byte Ptr, Device:Byte Ptr, DeviceBank:TBank, Decoder:Byte Ptr

Global UserCallBack:Byte Ptr


Rem
bbdoc: Loads a MP3 and return a TAudioSample.
End Rem

Method Load_MP3:TAudioSample(File$)
Local zeit%=MilliSecs()
......


But in the help file of other author you can often see code examples. How to add them into this help file?



...back from North Pole.

Skaven

when generating docs the generator looks for matching bmx files om the doc folder for that function or keyword etc

Scaremonger

I wrote a docmod tutorial years ago on the old Blitzmax forum. It can still be found here:

https://mojolabs.nz/posts.php?topic=68114

It may not be very current!

Si...

Midimaster

thank you! That was what I was looking for. Good explanation. This should become a part of the BlitzMax Help!
...back from North Pole.

Midimaster

I could build a documentation for my miniaudio.mod with the docmods.exe command. But there is still one thing I cannot understand...

I my documentation the Methodes appear in a alphabetic order. But if you have a look on the f.e. TSound() documentation it appears in a more thematic order.

Does somebody know how to switch this? There must be a command parameter for the docmode.exe, or?
...back from North Pole.

markcwm

The official docs are built with makedocs and third party docs are built with docmods, third party docs are sorted with list/array sort methods whereas makedocs doesn't. Try commenting one out in docmods, there's one on line 20 and one on 138.

Midimaster

Thanks... did not know that the source code of docmods.exe is "on board". Now I found it in "BlitzMaxNG/scr/docmods/". Thank you
...back from North Pole.

_PJ_

#7
Sorry for the "bump"

____________________________

Nevermind - the issue is resolved. After reading::
https://archive.blitzcoder.org/forums/bmx-tutorials/42290.html

I removed Superstrict (( it's redundant in Bmax-NG as superstrict is enabled by default )) and some empty lines, so the very first line of the source as well as re-running "build modules" and ensuring the naems of modules and sub-modules were all lowercase.
Following this, I ran docmods again and it generated the folder and files correctly!

____________________________




Some time ago, I wrote a module, placed it into the correct location, added the "module" statement etc. and included "bbdoc" lines etc. - previously, I had been able to build the docs entries correctly, but recently, since re-installing and updating NG I am unable to create the docs files...

When I run docmods.exe or if I choose "Rebuild Documentation" from within the IDE - a "docs" folder is created in the module's folder, but is empty...

Are there any paramters for docmods required, or do I need some specific requirements?

Unfortunately, the link shown above
https://mojolabs.nz/posts.php?topic=68114
is no longer valid, and I haven't been able to find any other clear instructions on the necessary requirements to ensure docs are generated for user-built modules.

This thread is the closest I could find, as other searches only dealt with the module code and compilation itself, not its documentation.

Is there any clear instruction abvailablke regarding the use of "bbdoc" entries in .bmx source, docmods and how to ensure the relevant html is generated in the right places?