flat assembler
Message board for the users of flat assembler.

Index > Main > AsmDoc - early demonstration

Author
Thread Post new topic Reply to topic
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
hi, this is first demnstration of my side project - AsmDoc.

It is intended to be documentation generator like DoxyGen or JavaDoc: all documentation is stored in special comments in source, side-by-side with things it describes. Lot of info can be found just by parsing sources.

This example is not really usable yet, but demonstrates basic capabilities. Sources are attached. Go on and try it Wink

PS: I did this project to create documentation for FASMLIB, and also to get practice in few new technologies. Namely:
- C++ coding
- Code::Blocks - Very nice open-source IDE for C++ language (and others)
- MinGW gcc - MinGW port of GNU Compiler Collection
- flex - Lexical Analyzer for using with C/C++

So don't be surprised if you find some stupidities in sources.


Description:
Download
Filename: AsmDoc - 0.0.0.1a.zip
Filesize: 166.9 KB
Downloaded: 231 Time(s)



Last edited by vid on 04 Jul 2007, 10:30; edited 1 time in total
Post 03 Jul 2007, 22:56
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
polygon7



Joined: 14 Aug 2003
Posts: 62
Location: Poznan, Poland
polygon7
vid wrote:

hi, this is first demnstration of my side project - AsmDoc.

It is intended to be documentation generator like DoxyGen or JavaDoc: all documentation is stored in special comments in source, side-by-side with things it describes. Lot of info can be found just by parsing sources.


I like it, it's really cool! Very Happy

vid wrote:

- Code::Project - Very nice open-source IDE for C++ language (and others)


Code::Blocks Wink

_________________
best regards
p7
Post 04 Jul 2007, 06:00
View user's profile Send private message Visit poster's website Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
polygon7 wrote:

vid wrote:

- Code::Project - Very nice open-source IDE for C++ language (and others)


Code::Blocks Wink

hell, thanks.
Post 04 Jul 2007, 10:29
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
tom tobias



Joined: 09 Sep 2003
Posts: 1320
Location: usa
tom tobias
vid wrote:

It is intended to be documentation generator like DoxyGen or JavaDoc: all documentation is stored in special comments in source, side-by-side with things it describes. Lot of info can be found just by parsing sources.
(1) Program = algorithm plus data structures. Will "parsing sources" reveal either one? In my opinion, NO!!! (It is most improbable that a computer program will reveal one's thoughts, that is why documentation is so much more important than CODE.)
(2) Documentation, in a proper PROGRAMMING environment, is performed BEFORE any code is written, not after the project is complete---Were Notre Dame Cathedral in Paris, or Paul's Cathedral in London, or Mark's Cathedral in Venice, constructed FIRST, and THEN an architect came along and designed them? I have forgotten the name of the beautiful castle and cathedral in Crakovia, but the same notion applies there too.
(3) Why in the world would anyone deliberately employ C, (or C++) rather than Asm for any purpose?
(4) A good starting point, to learn about documentation is gained by downloading the sources of FASM, and then observing what has, and what has NOT been done, during the past several years. For example, the current version, 1.67.21, dating from February 2007, includes a file, called fasm.txt, in which one finds this title: "Programmer's Reference Manual", with a version number of 1.66. Hmmm.
Within fasm, one finds a file called Assemble.inc, about which one may generously write, there exists a paucity of information, or, more accurately, NULL. NADA. Zero de conduit.
So, in my humble, or even in my arrogant, opinion, one may profit from providing some GROUND ZERO documentation about FASM, rather than wasting time with a C source documentation generator. Is this doc generator going to explain WHICH files perform WHICH function within FASM?
Post 06 Jul 2007, 09:11
View user's profile Send private message Reply with quote
shoorick



Joined: 25 Feb 2005
Posts: 1605
Location: Ukraine
shoorick
i have not tried it yet, but have to say about double ";;" - some sources may contain ";;",";;;" etc. at line start due to block commenting operation in some editors - may lead to wrong detecting by doc generator (?)
Post 06 Jul 2007, 10:23
View user's profile Send private message Visit poster's website Reply with quote
f0dder



Joined: 19 Feb 2004
Posts: 3170
Location: Denmark
f0dder
tom tobias: I think you have completely missed the point of this class of documentation system.

You're still supposed to have design documents "off the side", where you do your pre-programming planning, description of algorithms and data structures, et cetera. This class of docsys is in addition to your design documents, and describe the source itself. Things like arguments to functions, return values, invariants, etc.

Yes, you could keep this information in the external documentation as well, but it's easier to keep the info up-to-date when it's near the actual source code.
Post 06 Jul 2007, 11:42
View user's profile Send private message Visit poster's website Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
Quote:
(1) Program = algorithm plus data structures. Will "parsing sources" reveal either one? In my opinion, NO!!! (It is most improbable that a computer program will reveal one's thoughts, that is why documentation is so much more important than CODE.)

no, AsmDoc doesn't try to reveal anything about algorithm. For far future, i plan ability to parse declarations of data structures (struc directive and struct macro). However this is NOT main focus of AsmDoc. Main focus is to provide coder with ability to maintain documentation within sources.

Quote:
(2) Documentation, in a proper PROGRAMMING environment, is performed BEFORE any code is written, not after the project is complete

In "university programming" maybe yes, but not in real world application. Yes, there must be some general design of application thought before it is being written, ugly UML diagrams, data flow over big modules etc... AsmDoc is not aimed at this kind of documentation. It is intended for documentation of source code: description of arguments of function, return values, description of variables, etc. Useful for anyone who would ever have to tweak or use the code, or for documenting interfaces of libraries.

This kind of documentation is not written prior to writing code, and it is hell to maintain it separately from code. It just doesn't work, you have to do same change at least twice (in code and in docs). And if you forget to update documentation, it is hard to notice, because you seldom look at both places at same time.

Quote:
(3) Why in the world would anyone deliberately employ C, (or C++) rather than Asm for any purpose?

There are places where you need some assembly, at least some leaf functions. AsmDoc could be used to document assembly procs, DoxyGen for documenting. They could easily cooperate with XML functionality. I realize this isn't much, but i don't care.

As for the purpose, look at it from my point of view: I am developing FASMLIB. It should be library, that would be useful at least for learning assembly. I hope you agree understanding assembly is very important for C and C++ coders. This library needs documentation. I want to have proces of maintaining documentation as easy as possible, of course. That's why i wrote AsmDoc. It isn't anything big yet, it is a quick hack of less than week of work.

Quote:
Within fasm, one finds a file called Assemble.inc, about which one may generously write, there exists a paucity of information, or, more accurately, NULL. NADA. Zero de conduit.

name of labels are sort of documentation present there. They give you at least some idea of purpose of following code. Zero documentation would be in disassembled FASM, also without error code strings Wink

Quote:
So, in my humble, or even in my arrogant, opinion, one may profit from providing some GROUND ZERO documentation about FASM, rather than wasting time with a C source documentation generator. Is this doc generator going to explain WHICH files perform WHICH function within FASM?

no, but if anyone ever decides to write such document, this utility is going to make it much easier for him.

shoorick: What would you suggest instead of ";;"? It's absolutely no problem to tweak sources to accept anything else, but ";;" seems most logical to me. it's same in C and DoxyGen, some sources may already contain "///" that will fool DoxyGen, but people can live with it.
Post 06 Jul 2007, 11:49
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
shoorick



Joined: 25 Feb 2005
Posts: 1605
Location: Ukraine
shoorick
eg. ;>

do not think uncommented string in source will start from ">"
--------------
+ obligative following 1 space/tab to avoid code separators like:
;>>>>>>>>>.....
Post 06 Jul 2007, 12:36
View user's profile Send private message Visit poster's website Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
I was already thinking about letting user to set this, ";;" being default. It could be little problem with current design, but i think it will be possible.

Thanks for good idea Wink
Post 06 Jul 2007, 13:17
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
tom tobias



Joined: 09 Sep 2003
Posts: 1320
Location: usa
tom tobias
Let us consider, for example, "labels_list", which occurs four times in assemble.inc.

assembler_loop:
mov eax,[labels_list]

pass_done:
mov eax,[labels_list]

flush_display_buffer:
mov esi,[labels_list]

display_messages:
mov eax,[labels_list]

fudder has suggested, not improperly, nor unkindly, that I have
"completely missed the point of this class of documentation system"
regarding vid's documentation generator. I cannot dispute fudder's assertion, for he is correct: I do fail to appreciate how vid's program will teach us something about "labels_list", for example, what it is, or, where it is defined, or, (more importantly, in my opinion,) WHY IT, in particular, (and not something else) IS USED in each of these four circumstances. Perhaps most significantly, I fail to IMAGINE, because I am insufficiently clever, how vid's program will clarify anything about these four instances where "labels_list" is employed....
What could potentially be of considerable utility here, for this particular illustration, is a human hand generated, (as opposed to computer generated,) explanation (a) of these four individual lines of code, and (b) HOW this program of vid's would be able to create a comparable explanation, i.e. based upon "parsing sources". After parsing this source, with my human eyes, I am unable to explain anything about "labels_list". I do not know (a) where it originates (i.e. where it is defined), (b) what it contains, or (c) its purpose. I am further unable to explain how one could deduce the answers to these questions, simply by parsing this source code.
Post 07 Jul 2007, 07:58
View user's profile Send private message Reply with quote
bogdanontanu



Joined: 07 Jan 2004
Posts: 403
Location: Sol. Earth. Europe. Romania. Bucuresti
bogdanontanu
Apparently NaturalDocs does support ASM also ...

http://www.naturaldocs.org/about.html
Post 07 Jul 2007, 08:50
View user's profile Send private message Visit poster's website Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
bogdan: thanks, i didn't know about it. I am gonna test it. Slight problem with it: it requires Perl support, and only has HTML output. For that reason i couldn't use it in FASMLIB, but it might work fine for others.

Still, i believe having fine-tuned doc generator for assembly is good thing.

tom: just reread my last post please, it explains it:
Quote:
no [it can't], but if anyone ever decides to write such document, this utility is going to make it much easier for him.
Post 07 Jul 2007, 10:52
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
f0dder



Joined: 19 Feb 2004
Posts: 3170
Location: Denmark
f0dder
tom tobias: you again show that you missed the point Smile

The documentation-generator isn't supposed to just look at program structure and be able to explain everything that's going on from that. It requires that the programmer has placed specially crafted comments in the source for things like function description, arguments, return value, etc.

The actual source parsing is a bit more useful in high-level languages though, especially something like C++, because class diagrams etc. can be generated from parsing the source... with assembly you don't have such complex construct (except if you use one of the ObjAsm projects), but it could still analyse and graph physical file structure (includes, libraries, etc) - and this can be useful enough.

This automated structure analysis is only really useful when you do the "special comments" thing as well, though, and it should still be seen as a supplement to proper design docs, not a replacement for those - for reasons already listed.
Post 07 Jul 2007, 22:12
View user's profile Send private message Visit poster's website Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
tom: exactly as f0dder and i stated, analysis from code is just extra feature, not purpose. Purpose is to make it easy to maintain documentation along with code, not separately. If you ever tried to buidl maintain some procs's documentation separately from project, then you will know the hell it is (i HAVE tried it, and never want to try it again...)
Post 08 Jul 2007, 00:49
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
tom tobias



Joined: 09 Sep 2003
Posts: 1320
Location: usa
tom tobias
Thank you fudder and vid for your efforts to clarify my misunderstanding. Umm, just a thought, not a demand, for sure, but, would it be too insensitive on my part to ask vid, if you could pass this section of assembl.inc through your filter, to see what emerges? Perhaps then, obtuse as I undoubtedly am, it would be easier for anyone to comprehend just what exactly vid's newest C program accomplishes. I do not require elaboration of the WHOLE of assemble.inc, merely these four routines:
assembler_loop:
pass_done:
flush_display_buffer:
display_messages:
At present there is zero information in the source code, so it will be fun to read what emerges after passing the code through your filter.
Thanks.
Smile
Post 08 Jul 2007, 18:18
View user's profile Send private message Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
tom: of course, utility now emerges only that there are labels with those names declared. Nothing more. It is NOT a code analysis tool, code analysis is just an extra feature, not even required for this kind of tool. You are focusing at wrong feature of AsmDoc.

But if anytime anyone decides to make documentation if fasm, he could comment it like this:
Code:
;; does one pass of assembling
;; @arg edi destination buffer
;; @arg esi source code
;; @arg [memory] allocated memory
assembler_loop: 

;; checks after assembling pass is done
pass_done: 

... etc ...    


maintaing such documentation would be much easier for him
Post 08 Jul 2007, 20:02
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
tom tobias



Joined: 09 Sep 2003
Posts: 1320
Location: usa
tom tobias
vid wrote:
Lot of info can be found just by parsing sources...
fudder wrote:
...you again show that you missed the point...

vid wrote:
...of course, utility now emerges only that there are labels with those names declared.

In other words, this "utility" may offer assistance to those engaged in elaborating documentation "just by parsing sources", if, and only if, the source code ALREADY possesses some kind of text commentary. I remain unsure what "the point" is, but I do believe that I understand MY POINT:
Programs = algorithm plus data structures.
Code = gobbledygook.
FASM proudly represents the latter category.
In my opinion, the utility of vid's new utility is to readily distinguish, without acrimony, (and irrespective of an author's ostensibly lofty status within some kind of academic circle,) between these two categories of creative "art".
Post 09 Jul 2007, 07:44
View user's profile Send private message Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
Quote:
Lot of info can be found just by parsing sources...

type of information that can be obtained by parsing well-formated sources:
- names of all defined symbol
- types of symbols (label, dword variable, highlevel procedure)...
- which symbol is defined in which file / line
- which symbol is referenced in which file/routine (dependency tree)
- initial value of variable
- list of arguments for procedure
maybe more in future

Rest of info has to be included in special comments.

I hope at least now it is clear. I can't really tell to which your program/code category it falls for you, that decision is on you. But regardless of your opinion, i think this is a useful option for documentation of assembly projects.
Post 09 Jul 2007, 10:51
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
tom tobias



Joined: 09 Sep 2003
Posts: 1320
Location: usa
tom tobias
vid wrote:
I can't really tell to which your program/code category it falls for you, that decision is on you.

Apologies for having written with excessive verbosity. I was not referring to YOUR program, vid, when I juxtaposed code and program, I was referring to FASM. I have never examined your source code, and am both unlikely to do so, and incompetent to do so, since you have stated that the source of your program is written in C, a language I abandoned as utterly useless a quarter century ago.
Post 09 Jul 2007, 12:48
View user's profile Send private message Reply with quote
vid
Verbosity in development


Joined: 05 Sep 2003
Posts: 7105
Location: Slovakia
vid
Actually, it's C++. There was no good reason to do thing like this in C, or assembly.
Post 09 Jul 2007, 13:11
View user's profile Send private message Visit poster's website AIM Address MSN Messenger ICQ Number Reply with quote
Display posts from previous:
Post new topic Reply to topic

Jump to:  


< Last Thread | Next Thread >
Forum Rules:
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum


Copyright © 1999-2020, Tomasz Grysztar.

Powered by rwasa.