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

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.

I like it, it's really cool!



Code::Blocks

hell, thanks.

(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?

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 (?)

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.

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.


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.


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.


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


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.

eg. ;>

do not think uncommented string in source will start from ">"
--------------
+ obligative following 1 space/tab to avoid code separators like:
;>>>>>>>>>.....

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

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.

Apparently NaturalDocs does support ASM also ...

http://www.naturaldocs.org/about.html

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:

tom tobias: you again show that you missed the point

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.

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...)

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.

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:


maintaing such documentation would be much easier for him

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".

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.

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.

Actually, it's C++. There was no good reason to do thing like this in C, or assembly.