ObjAsm Documentation

[Biterider]

Hi
During my last holidays I read a lot of new developments and trends in other languages. I've found some already implemented in ObjAsm, like composition, but there are others that are really new.

But before I start a new chapter, I want to finish two things:
1. Finish the UEFI support
2. Improve the ObjMem documentation

I am looking for feedback, especially the documentation issue seems to be a special one because I don't know what is expected.
It can be a pdf document, an application like ObjectExplorer or something else...

Regards, Biterider

[fearless]

I have recently been using readthedocs for hosting documentation. It uses a markdown like language called sphinx. I used it with some of the ModernUI stuff, and most recently when i updated my DateTime Library: https://datetime-library.readthedocs.io/en/latest/ - you can specify sphinx to auto build the html version, also pdf, epub & html zipped.

Lower left panel is opened by clicking it and it expands up to reveal download options for the readthedocs project:


But incidentally I was looking at zeal again the other day (https://masm32.com/board/index.php?topic=9581.0 and https://github.com/zealdocs/zeal) and came across docdash (https://doc2dash.readthedocs.io/en/stable/index.html - zeal uses the dash docsets) which converts the sphinx like documentation to a docset for use in zeal.
So once you create the sphinx documentation and using docdash you would have various doc sources: online, pdf, epub, html zipped, and a zeal docset.

Here is an example of what the rst file looks like for a DTDay function:

Code Select Expand


.. _DTDay:

===================================
DTDay
===================================

Get the day part of a date & time string.
   
::

   DTDay PROTO lpszDateTimeString:DWORD, DateFormat:DWORD


**Parameters**

* ``lpszDateTimeString`` - Pointer to a buffer containing the date & time string to retrieve the **day** portion from. The format of the date & time string is determined by the ``DateFormat`` parameter.
* ``DateFormat`` - Value indicating the date & time format used in the buffer pointed to by ``lpszDateTimeString`` parameter. The parameter can contain one of the following constants as listed in the :ref:`DateTime Formats<DateTime Formats>` page and as defined in the ``DateTime.inc`` include file.


**Returns**

Returns the day value in ``EAX``


**Example**

::

   .data
   DateTimeStringValue db "2008/03/21 16:21:01:00",0
   
   .data?
   DayValue dd ?
   
   .code
   Invoke DTDay, Addr DateTimeStringValue, CCYYMMDDHHMMSSMS
   mov DayValue, eax ; save day part of date value to data variable
   ; eax should contain 21


**See Also**

:ref:`DTMonth<DTMonth>`, :ref:`DTYear<DTYear>`, :ref:`DTIsLeapYear<DTIsLeapYear>`, :ref:`DTDayOfWeek<DTDayOfWeek>`, :ref:`DateTime Formats<DateTime Formats>`

and this is what that looks like when readthedocs renders it:




I can go over some of the bits and pieces in the rst file to help explain what they do, and to speed up the learning process.

Also i use a batch file to help create the .rst files for functions - kinda like a template for them and then edit to change the details and add parameters and notes etc.

Code Select Expand


@echo off

rem delete temp files
for /f "Tokens=*" %%a in ('dir *. /b/a-d') do (
    del %%a
)

echo.>DTGetDateTime
echo.>DTDateFormat
echo.>DTDateTimeStringToDwordDateTime
echo.>DTDwordDateTimeToDateTimeString
echo.>DTDwordDateToJulianDate
echo.>DTJulianDateToDwordDate
echo.>DTDateTimeStringToJulianMillisec
echo.>DTJulianMillisecToDateTimeString
echo.>DTDwordDateTimeToJulianMillisec
echo.>DTJulianMillisecToDwordDateTime
echo.>DTDateTimeStringToUnixTime
echo.>DTUnixTimeToDateTimeString
echo.>DTDwordDateTimeToUnixTime
echo.>DTUnixTimeToDwordDateTime
echo.>DTDwordTimeToMillisec
echo.>DTMillisecToDwordTime
echo.>DTDayOfWeek
echo.>DTIsLeapYear
echo.>DTDay
echo.>DTMonth
echo.>DTYear
echo.>DTDateStringsCompare
echo.>DTDateStringsDifference
echo.>DTDateTimeStringsDifference



rem bare files to rst   

for /f "Tokens=*" %%a in ('dir *. /b/a-d') do (
    echo... _%%a:>%%a.rst
    echo.>>%%a.rst
    echo ===================================>>%%a.rst
    echo %%a >>%%a.rst
    echo ===================================>>%%a.rst
    echo.>>%%a.rst
    echo... delete this starting at \.\. and type description>>%%a.rst
    echo.>>%%a.rst   
    echo ::>>%%a.rst
    echo.>>%%a.rst
    echo    %%a^(^)>>%%a.rst
    echo.>>%%a.rst
    echo.>>%%a.rst
    echo **Parameters**>>%%a.rst
    echo.>>%%a.rst
    echo * **>>%%a.rst
    echo * **>>%%a.rst
    echo * **>>%%a.rst
    echo.>>%%a.rst
    echo.>>%%a.rst
    echo **Returns**>>%%a.rst
    echo.>>%%a.rst
    echo.>>%%a.rst
    echo.>>%%a.rst
    echo **Notes**>>%%a.rst
    echo.>>%%a.rst
    echo.>>%%a.rst
    echo.>>%%a.rst
    echo **Example**>>%%a.rst
    echo.>>%%a.rst
    echo ::>>%%a.rst
    echo.>>%%a.rst
    echo    %%a^(^)>>%%a.rst
    echo.>>%%a.rst
    echo **See Also**>>%%a.rst
    echo.>>%%a.rst
    echo :ref:``, :ref:`` >>%%a.rst
    echo.>>%%a.rst
) 

rem delete temp files
for /f "Tokens=*" %%a in ('dir *. /b/a-d') do (
    del %%a > nul
)

del "%a.rst" > nul
Once i have created them, i rename the batch file to prevent accidentally clicking it again and overwriting any work done ;-)

[Biterider]

Hi fearless
Thank you for this great content
I'll wait a little longer to get more answers, but I'm sure there will be a suitable output format from the tools you mentioned.
In any case, I need a parser to extract the actual data from the source files where I put the relevant information about the library procedures.

Biterider

[fearless]

I had recently thought similar about extracting content from source files and converting or creating sphinx rst files from them. Looked at other automatic documentation software, but very little support for asm - maybe one had support for nasm i think. Anyway I started a project called DocAsm to do the asm to rst - still working on it and other projects - I keep getting sidetracked from one project to another lately :D

[HSE]

Hi Biterider!!

1. Finish the UEFI support
2. Improve the ObjMem documentation

especially the documentation issue seems to be a special one

I think that is really hard to write (good) documentation and take a lot of time, and grow with users questions, etc.

Perhaps is better a more modest goal like a help. The more simple way is just a list of functions and arguments, later how they can be grouped, how they are related, some features that apply to all or a group, ancester and descendent functions, sources, uses, examples, etc. and at some point you have a complete reference.

Format is secondary, but I think are hard to beat ".chm" files, that is offline, can show a complex tree, index, search, content sequences, etc.

HSE

[Biterider]

Hi
I worked out one of fearless ideas and created a .cmd file to extract the procedure header information.
From there, it was just a short step to create a PDF file. 

Since the final file is larger than the maximum upload limit, I'm posting a reduced version.
Please check if it meets the requirements.

Biterider

[HSE]

Hi Biterider!!

ObjMem functions collection and library. Part A. Function briefs and nomenclature. - ObjAsm Reference - Volume II       Document version 1.0

This document describes all the methods and other content of the ObjAsm project's main open source static library called ObjMem.lib.

ObjAsm components and project developments take advantage of optimized assembly procedures. The source code of this functions are included in ObjAsm package, as well as an static library containing them, named ObjMem.lib. Also an include file to use libray in object oriented or plain assembly programming, and command files to build the library, are provided in package. This document contain summaries of all current functions and other valuable information for procedures use, modification and further improvement.

(This perhaps can be translated to true english  )

HSE

[Biterider]

Hi HSE
Thanks!
At this point, this document is more of a proof of concept, but I like the idea of turning this into a Volume II.
Additions and corrections come at the right time.

I am manipulating the document to automatically add links, which should be useful to open a file in case it needs to be consulted.

Biterider

[HSE]

Hi Biterider!

this document is more of a proof of concept,

The concept is that this is not the documentation, just an small part of that. (even if no other parts never come out  )

HSE

[Biterider]

Hi
File links to the main asm file are now added, and in the case and include to the "Common" folder, a second link is also added.
The result can be seen here https://github.com/ObjAsm/ObjAsm-C.1/blob/UEFI_Support/Help/ObjAsm_Reference_Volume-II.pdf?raw=true

Biterider

[Biterider]

Hi
Using the same tools as for Volume II, I extracted the information from the macros in the ObjAsm\Code\Macros directory and created Volume III.
The result is here https://github.com/ObjAsm/ObjAsm-C.1/blob/UEFI_Support/Help/ObjAsm_Reference_Volume-III.pdf?raw=true

Now, the documentation covers almost everything and is easy to update. 

Biterider

[fearless]

if you add ?raw=true to the end of the urls for the docs then they should open the pdf automatically in the browser (firefox) or download directly.

[Biterider]

Wow, so cool 
Thanks fearless


Biterider

[Biterider]

Hi
Looking at the first post of this thread, the 2 main goals are now achieved.   
So I made a pull request to merge the UEFI branch and switched back to the master branch.
From now on, all new changes will be made in this branch.

Thanks for all the help and input. 

Biterider