Searching \ for '[OT] doxyGen' in subject line. ()
Make payments with PayPal - it's fast, free and secure! Help us get a faster server
FAQ page: www.piclist.com/techref/index.htm?key=doxygen
Search entire site for: 'doxyGen'.

Exact match. Not showing close matches.
PICList Thread
'[OT] doxyGen'
2009\05\15@090058 by Tamas Rudnai

face picon face
Hi Guys,

Is anybody uses doxyGen for documenting code?

I just started to use it and could not find any information about how to
produce a main page -- except that you have to put everything in source
files as comments so that if you need to write some chapters onto the main
page (or any other related pages) then you have to create a header file (or
some other source file) that contains doxyGen formatted comments only.

I found it ugly to put everything into .h files so if you have any better
idea? Also if you know any tool for automatically generating indexes to
anchors / function documents?

Thanks,
Tamas
--
http://www.mcuhobby.com

2009\05\15@092151 by Wouter van Ooijen

face picon face
Tamas Rudnai wrote:
> Hi Guys,
>
> Is anybody uses doxyGen for documenting code?

I have not used it. I did consider it, but I don't like the
documentation of the projects I see on the web that say 'generated by
doxygen', because it seems to be just a list of documented functions,
without any higher structure. That might be related to your findings.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\15@093745 by WH Tan

picon face
2009/5/15 Wouter van Ooijen wrote:
> I have not used it. I did consider it, but I don't like the
> documentation of the projects I see on the web that say 'generated by
> doxygen', because it seems to be just a list of documented functions,
> without any higher structure. That might be related to your findings.

Hi Wouter,

Did you manage to find an alternative?

Thanks & best regards,

--
WH Tan

2009\05\15@095207 by Tamas Rudnai

face picon face
On Fri, May 15, 2009 at 2:21 PM, Wouter van Ooijen <spam_OUTwouterTakeThisOuTspamvoti.nl> wrote:

> I have not used it. I did consider it, but I don't like the
> documentation of the projects I see on the web that say 'generated by
> doxygen', because it seems to be just a list of documented functions,
> without any higher structure. That might be related to your findings.
>

I think it is only because they do not really documenting or they might
think that the tool will do their job.

Basically what doxyGen can do automatically is:

- generating call tree
- generating call graphs with external tools, like
kdevelop.org/HEAD/doc/api/html/structInitDeclaratorAST.html
- listing up the classes / members / functions / variables like
http://www.vtk.org/doc/nightly/html/hierarchy.html

But it is more useful is when you create your documentation -- which sits in
the source code, so it is easy to maintain and later on you can generate the
documentation gathering the info directly from the source files producing
the type of output you like (HTML, or Windows Help, or PDF -- it depends on
you really, and the principal is quite similar to the XML)

For example:
http://dbus.freedesktop.org/doc/api/html/group__DBusHashTable.html#gbd5df8141cff5908c8c856bb9e6715b8

or mySQL:
http://dev.mysql.com/sources/doxygen/mysql-5.1/group__DBA.html#gb295f253d9f31178001945daff1def5c

Thanks,
Tamas
--
http://www.mcuhobby.com

2009\05\15@102817 by Isaac Marino Bavaresco

flavicon
face
Wouter van Ooijen escreveu:
> Tamas Rudnai wrote:
>  
>> Hi Guys,
>>
>> Is anybody uses doxyGen for documenting code?
>>    
>
> I have not used it. I did consider it, but I don't like the
> documentation of the projects I see on the web that say 'generated by
> doxygen', because it seems to be just a list of documented functions,
> without any higher structure. That might be related to your findings.
>  

I use Doxygen, just the basic.

I suppose that there is some way to add external files to the documentation.

There is a configuration (EXTRACT_ALL if I remember it right) that makes
Doxygen generate documentation for undocumented structures (very basic
but useful).

Doxygen doesn't document only functions, it may document functions,
variables, types, macros, etc.

A nice feature is the call/callee graph, very useful to understand how
the functions interact, estimate maximum stack depth, etc. (it must
analyze the .c files also to do this).

In my opinion it is a must have.

Regards,

Isaac


__________________________________________________
Faça ligações para outros computadores com o novo Yahoo! Messenger
http://br.beta.messenger.yahoo.com/

2009\05\15@103217 by Wouter van Ooijen

face picon face
> For example:
> dbus.freedesktop.org/doc/api/html/group__DBusHashTable.html#gbd5df8141cff5908c8c856bb9e6715b8
>
> or mySQL:
> http://dev.mysql.com/sources/doxygen/mysql-5.1/group__DBA.html#gb295f253d9f31178001945daff1def5c

Hmmmm, I like neither. A lot of "here is the list of all <>'s". But of
course, that is probably not the tool's fault.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\15@103238 by Wouter van Ooijen

face picon face
> Hi Wouter,
>
> Did you manage to find an alternative?

For now I wrote my own doc extracter/formatter. It is specific to my mkt
project, and generates HTML only. http://www.voti.nl/mkt/manual/ is what
it generates, http://www.voti.nl/mkt/mkt.py is both the extract/format
tool and the source for the manual (it is also  the tool itself - I like
having everything in one big file).

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\15@105725 by WH Tan

picon face
2009/5/15 Wouter van Ooijen wrote:
> For now I wrote my own doc extracter/formatter. It is specific to my mkt
> project, and generates HTML only. http://www.voti.nl/mkt/manual/ is what
> it generates, http://www.voti.nl/mkt/mkt.py is both the extract/format
> tool and the source for the manual (it is also  the tool itself - I like
> having everything in one big file).

Thanks Wouter.  The HTML page generated is really nice!  Great jobs.

--
WH Tan

2009\05\15@124949 by Wouter van Ooijen

face picon face
> Thanks Wouter.  The HTML page generated is really nice!  Great jobs.

The html is very basic, no big deal. I did try to generate .rtf, but
that was not as easy.

The framed parts are tables. Somehow I can't avoid an empty line at the
top (or was it bottom?). But that empty line does not show when printed!

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\16@081136 by Gerhard Fiedler

picon face
Tamas Rudnai wrote:

> Is anybody uses doxyGen for documenting code?
>
> I just started to use it and could not find any information about how
> to produce a main page -- except that you have to put everything in
> source files as comments so that if you need to write some chapters
> onto the main page (or any other related pages) then you have to
> create a header file (or some other source file) that contains
> doxyGen formatted comments only.
>
> I found it ugly to put everything into .h files so if you have any
> better idea? Also if you know any tool for automatically generating
> indexes to anchors / function documents?

Doxygen is for documenting the code that you write. It's main purpose is
to extract the code structure, embedded comments and create a document
from this that is better readable than the pure code. This it does
rather well, IMO.

The first FAQ <http://www.stack.nl/~dimitri/doxygen/faq.html> shows how
to get some text onto the main page (\mainpage). When you, for example,
write a library, you generally already have a main include file. This
would be the one where you put this. \htmlinclude and \page may also be
helpful.

Doxygen has quite a few commands and configuration options; I recommend
reading at least the reference section more than once, completely. This
doesn't take too long :) For getting the most benefit out of it, I think
it is also important that you experiment a bit with the code, its markup
and the Doxygen configuration until you get your code documentation to
look like you want it -- and then consistently use the same form for all
your code.

FWIW, I never create header files with Doxygen text only. I use the
header files that I already use in my code to document the code that I
write. The only thing that's different with using Doxygen is that I add
the appropriate tags for extraction, and that I do this in a more formal
and consistent way.

Doxygen extracts a documentation of the structure of your code. If you
don't like what you see, chances are that either you haven't used it
appropriately (tags or configuration not to your liking) or that the
structure of the code is not to your liking :)

Gerhard

2009\05\16@083232 by Wouter van Ooijen

face picon face
> Doxygen extracts a documentation of the structure of your code. If you
> don't like what you see, chances are that either you haven't used it
> appropriately (tags or configuration not to your liking) or that the
> structure of the code is not to your liking :)

Or: you want something different than what doxygen was made for. I
mostly want to document tool that provides (among other things) an API,
I definitely do not want to document the code of the tool, or the code
behind the API.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\16@092808 by Tamas Rudnai

face picon face
On Sat, May 16, 2009 at 1:11 PM, Gerhard Fiedler <.....listsKILLspamspam@spam@connectionbrazil.com
> wrote:

> The first FAQ <http://www.stack.nl/~dimitri/doxygen/faq.html<www.stack.nl/%7Edimitri/doxygen/faq.html>>
> shows how
> to get some text onto the main page (\mainpage). When you, for example,
> write a library, you generally already have a main include file. This
> would be the one where you put this. \htmlinclude and \page may also be
> helpful.
>

Sorry, maybe my post was not clear. I understand what were you saying and I
am using these commands already. The thing is that I am documenting an
entire module in a large software with three sub modules and few hundred
source files. For these I would need much more than the list of functions. I
would need to write basically a book with couple of chapters at the
beginning so the enitre concept of the modules and sub modules, the
development enviroment, used tools etc and the history behind it would be
there. The first approach was to do it in the traditional way using word
processor and then merge it somehow with the doxyGen generated output. Then
I realised doxyGen is capable of doing that already, only that have to use
these commands you have mentioned and it was so easy to generate the doc
with these chapters together while the results was impressive to me -- nice,
well formatted document. The reason is doing in that way better are:

1. The source of the document is plain text which is perfect for source
control system
2. All the documentation together with the function descriptions and module
structure can be processed in one go
3. As using one system if I would like to change on the style I have to make
the modification only once and n one place

FWIW, I never create header files with Doxygen text only. I use the
> header files that I already use in my code to document the code that I
> write. The only thing that's different with using Doxygen is that I add
> the appropriate tags for extraction, and that I do this in a more formal
> and consistent way.
>

The only thing I would need to do that because those chapters are getting
bigger therefore it would disturb the developers later on. Unfortunately I
am the opposite to Wouter in that way that I do not like one big file
containing everything but a structured file set with logically separated
blocks. While a function header, a variable description and todos, bug lists
are placed in the source code (as it should be) these chapters needs a
separation for sure.

I do not really like the .h file trick to put doxyGen documents / pages in
it. So the original question really was if I can use a .txt or something
like that which clearly indicates what is this file about and doxyGen can
still  pick it up and use the text and the commands from it without using
any language related commenting methods.

Thanks
Tamas
--
http://www.mcuhobby.com

2009\05\16@093141 by Tamas Rudnai
face picon face
On Sat, May 16, 2009 at 1:31 PM, Wouter van Ooijen <wouterspamKILLspamvoti.nl> wrote:

> Or: you want something different than what doxygen was made for. I
> mostly want to document tool that provides (among other things) an API,
> I definitely do not want to document the code of the tool, or the code
> behind the API.
>

It could be the case. It seems to me that doxyGen physically is capable of
doing what I want, however, conceptionally they never thought is someone
would like to do something like that.

Tamas
--
http://www.mcuhobby.com

2009\05\16@180310 by Gerhard Fiedler

picon face
Tamas Rudnai wrote:

> The reason is doing in that way better are:
>
> 1. The source of the document is plain text which is perfect for
> source control system
> 2. All the documentation together with the function descriptions and
> module structure can be processed in one go
> 3. As using one system if I would like to change on the style I have
> to make the modification only once and n one place

No contest from me :)

{Quote hidden}

Ah, now I understand. I've never done this.

If the explanatory text you're writing doesn't contain any
Doxygen-specific tags (like links), maybe you can include only a link to
your documentation on the main page, and then simply include the files
(e.g. HTML format) with the Doxygen-generated files. Is simple with some
output formats (the ones that contain a bunch of separate files, like
HTML), not so simple with others (the ones that collect all generated
files into one, like Windows Help).

If you want Doxygen to parse your explanatory text (for links etc), you
probably can work with FILE_PATTERNS and EXTENSION_MAPPING to include
the extensions you want, and map them correctly. It should be possible
to add e.g. .txt or .doxy as extension to FILE_PATTERNS and map it to
use e.g. the C parser (so that they are treated in the same way an
include file would be treated). (I'd probably use .doxy rather than
.txt, in case someone else wants to add a simple text file that
shouldn't be parsed by Doxygen. This also could help to indicate to your
language-sensitive editor to color the file as Doxygen file -- or maybe
treat it as e.g. C file, in case you already have the tag coloration
included there :)

See also <http://www.stack.nl/~dimitri/doxygen/config.html>

Gerhard

2009\05\16@182420 by Gerhard Fiedler

picon face
Wouter van Ooijen wrote:

>> Doxygen extracts a documentation of the structure of your code. If
>> you don't like what you see, chances are that either you haven't
>> used it appropriately (tags or configuration not to your liking) or
>> that the structure of the code is not to your liking :)
>
> Or: you want something different than what doxygen was made for. I
> mostly want to document tool that provides (among other things) an
> API, I definitely do not want to document the code of the tool, or
> the code behind the API.

Do I understand you correctly: you want to document an API, and not the
code that implements the API? If so, this definitely can be done with
Doxygen.

Doxygen has the capability of generating different sets of
documentation: e.g. an external documentation (that could be the API
doc, for the users of the API) and an internal documentation (that could
be the code documentation, for the developers of the API). Or, if you
don't want the internal documentation, you can generate only the
external documentation, which could extract only the parts of the code
that declare the API -- no implementation details, no internal
interfaces would appear in the Doxygen documentation.

Is this what you mean? In this case, your "or" would most likely be
included in my "haven't used it appropriately" :)

Gerhard

2009\05\17@015849 by Paul Hutchinson

picon face
> -----Original Message-----
> From: .....piclist-bouncesKILLspamspam.....mit.edu [EraseMEpiclist-bouncesspam_OUTspamTakeThisOuTmit.edu]On Behalf
> Of Gerhard Fiedler
> Sent: Saturday, May 16, 2009 6:03 PM
>
<snip>
>
> Ah, now I understand. I've never done this.
>
<snip>
>
> If you want Doxygen to parse your explanatory text (for links etc), you
> probably can work with FILE_PATTERNS and EXTENSION_MAPPING to include
> the extensions you want, and map them correctly. It should be possible
> to add e.g. .txt or .doxy as extension to FILE_PATTERNS and map it to
<snip>

Like Gerhard, I've not needed to do this with Doxygen but I liked Tamas'
idea so I gave it a try.

It turns out to be easy, I created files for additional documentation with a
.dox extension containing only Doxygen comments. The files used the examples
from the Doxygen manual \mainpage and \page command sections.

Then I added *.dox to the FILE_PATTERNS directive in the config file. It
worked without mapping the .dox file extension so I guess Doxygen defaults
to the C parser on unknown types.

Paul Hutch

> See also <http://www.stack.nl/~dimitri/doxygen/config.html>
>
> Gerhard

2009\05\17@025429 by Wouter van Ooijen

face picon face
> Is this what you mean? In this case, your "or" would most likely be
> included in my "haven't used it appropriately" :)

The calling interface (function signatures and suchlike) is only a small
part of what I want to describe. Some functions are described in
isolation, but most are bundled and only the bundle is described.
Descriptions are grouped in chapters, which will haev other text (like
an introduction). I would estimate that the calling interface is not
more than 20% of the document.

In most cases both the C and the ARM assembler calling interface must be
described. (The actual code can be in C or Assembler.)

The documentation contains example programs. Those must be exported to
files.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\17@051539 by cdb

flavicon
face
Would Source Publisher do what you requiring?

http://www.scitools.com

Colin
--
cdb, colinspamspam_OUTbtech-online.co.uk on 17/05/2009

Web presence: http://www.btech-online.co.uk  

Hosted by:  http://www.1and1.co.uk/?k_id=7988359







2009\05\17@151114 by Gerhard Fiedler

picon face
Wouter van Ooijen wrote:

>> Is this what you mean? In this case, your "or" would most likely be
>> included in my "haven't used it appropriately" :)
>
> The calling interface (function signatures and suchlike) is only a
> small part of what I want to describe. Some functions are described
> in isolation, but most are bundled and only the bundle is described.
> Descriptions are grouped in chapters, which will haev other text
> (like an introduction). I would estimate that the calling interface
> is not more than 20% of the document.
>
> In most cases both the C and the ARM assembler calling interface must
> be described. (The actual code can be in C or Assembler.)
>
> The documentation contains example programs. Those must be exported
> to files.

I wrote: "Doxygen extracts a documentation of the structure of your
code. If you don't like what you see, ..."

It seems to me that you don't want a documentation of the structure of
your code; you seem to want a user manual or something the like. I take
this from your comment that "the calling interface is not more than 20%
of the document."

In this case, Doxygen doesn't seem to be the right tool, as only 20% of
what you want is what it does primarily. However, you still may be able
to use Doxygen-generated output as basis for those 20%. The advantage
would be that you don't have to copy changes in those 20% from the code
to the documentation.

OTOH, it may be possible to generate what you want with Doxygen. But
you'd probably have to study it quite a bit and adapt to its
capabilities when writing your documentation.

Gerhard

2009\05\17@160938 by Wouter van Ooijen

face picon face
> It seems to me that you don't want a documentation of the structure of
> your code; you seem to want a user manual or something the like.

Correct. not that I am not the OP, I am just a white noise source.

What has put me on the wrong foot is that I see some projects on the web
for which I expected to find user documentation, but I found something
generated by Doxygen. The fault is probably not doxygen's, but rather
the mismatch between my expectation and what the project put on their site.

I doubt I could use doxygen for the 20%, for one thing I want to
generate both C and Assembler (potentially for multiple CPU's) calling
instructions from a single source.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\17@185641 by Gerhard Fiedler

picon face
Wouter van Ooijen wrote:

>> It seems to me that you don't want a documentation of the structure
>> of your code; you seem to want a user manual or something the like.
>
> Correct. not that I am not the OP, ...

Yes, I know this -- but you seem to be interested enough to discuss it
:)

> ... I am just a white noise source.

You are rarely :)


> What has put me on the wrong foot is that I see some projects on the
> web for which I expected to find user documentation, but I found
> something generated by Doxygen. The fault is probably not doxygen's,
> but rather the mismatch between my expectation and what the project
> put on their site.

Probably. Doxygen is not the best tool to write high-level overviews,
but that's similar to saying that Word isn't the best tool to make
calculations :)

Also, it can't be expected from Doxygen to go over badly written and
poorly documented source code and generate a valuable high-level
documentation.

Documentation that is suited to be added to sources and then be
extracted is where Doxygen is good at. If you don't want to add your
documentation to your sources or if it isn't well-suited for this for
some reason, there is no need to use a documentation extractor/generator
-- which is what Doxygen is.

> I doubt I could use doxygen for the 20%, for one thing I want to
> generate both C and Assembler (potentially for multiple CPU's)
> calling instructions from a single source.

There is nothing that would prevent you from using Doxygen for this. You
have to write the assembly calling sequence for each target CPU anyway,
and if you write it in the function's header comment, it can be
extracted by Doxygen. It really boils down to whether you want it to be
with the source and extracted (meaning Doxygen can be useful) or whether
you want to write it somewhere separately (meaning Doxygen can't be
useful).

The advantage, of course, of writing it in the function header comment
is that the chances are higher that if you change the function
prototype, you also change the associated comment -- and this is then
automatically extracted into the documentation. Changing the function
prototype in the user manual, in a far-away manual source, is more
likely to be forgotten.

You may need to use a few tags for that (like \code, for example), but
you need this or something similar in any form of documentation
generation that's above plain text.

Gerhard

2009\05\18@024137 by Wouter van Ooijen

face picon face
> There is nothing that would prevent you from using Doxygen for this. You
> have to write the assembly calling sequence for each target CPU anyway,
> and if you write it in the function's header comment, it can be
> extracted by Doxygen.

OK, but could it generate *both* C and asm calling documentation from
one source? Currently I write something like

         #interface mkt_pin_direction
            #parameter N unsigned int
               number of the IO pin
            #parameter D unsigned int
               direction for the pin

From this is generated:

//  (C, C++)
void mkt_pin_direction(
   unsigned int N  //  number of the IO pin
   unsigned int D  //  direction for the pin
);

//  (ARM assembler)
subroutine mkt_pin_direction
   R0 : N          (unsigned int)       //  number of the IO pin
   R1 : D          (unsigned int)       //  direction for the pin

> It really boils down to whether you want it to be
> with the source and extracted (meaning Doxygen can be useful) or whether
> you want to write it somewhere separately (meaning Doxygen can't be
> useful).

In my case it's a bit complex: everything (C code, assembler code,
documentation, and more) is in one Python source.

> The advantage, of course, of writing it in the function header comment
> is that the chances are higher that if you change the function
> prototype, you also change the associated comment -- and this is then
> automatically extracted into the documentation. Changing the function
> prototype in the user manual, in a far-away manual source, is more
> likely to be forgotten.

I agree with that. I try to keep the generating source for the code and
the documentation close.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\18@025749 by Xiaofan Chen

face picon face
On Mon, May 18, 2009 at 2:40 PM, Wouter van Ooijen <@spam@wouterKILLspamspamvoti.nl> wrote:
>> There is nothing that would prevent you from using Doxygen for this. You
>> have to write the assembly calling sequence for each target CPU anyway,
>> and if you write it in the function's header comment, it can be
>> extracted by Doxygen.
>
> OK, but could it generate *both* C and asm calling documentation from
> one source? Currently I write something like
>
>          #interface mkt_pin_direction
>             #parameter N unsigned int
>                number of the IO pin
>             #parameter D unsigned int
>                direction for the pin
>

Maybe Python/Perl can come to the rescue. I have not used doxygen
myself (never written any big codes myself), but google found this.
http://www.stack.nl/~dimitri/doxygen/faq.html
http://rudy.mif.pg.gda.pl/~bogdro/inne/asm4doxy.txt

Not so sure if that helps...

--
Xiaofan http://mcuee.blogspot.com

2009\05\18@055832 by Tamas Rudnai

face picon face
On Sat, May 16, 2009 at 11:03 PM, Gerhard Fiedler <
KILLspamlistsKILLspamspamconnectionbrazil.com> wrote:

> If you want Doxygen to parse your explanatory text (for links etc), you
> probably can work with FILE_PATTERNS and EXTENSION_MAPPING to include
> the extensions you want, and map them correctly. It should be possible
> to add e.g. .txt or .doxy as extension to FILE_PATTERNS and map it to
>
...

Thanks for that! .DOX works fine, except a bit of weird behaviour that if I
put anything other than a C style comment then doxyGen will not pick it up.
Anyway, it seems to me good enough to start with.

Thanks
Tamas
--
http://www.mcuhobby.com

2009\05\18@060056 by Tamas Rudnai

face picon face
On Sun, May 17, 2009 at 10:15 AM, cdb <RemoveMEcolinTakeThisOuTspambtech-online.co.uk> wrote:

> Would Source Publisher do what you requiring?
>
> http://www.scitools.com
>

Thanks Colin,

Not exactly what I was looking for, however, that's an interesting tool
indeed. Maybe I will try that to see if that is any useful for the
developers.

Thanks,
Tamas
--
http://www.mcuhobby.com

2009\05\18@060440 by Tamas Rudnai

face picon face
On Mon, May 18, 2009 at 7:40 AM, Wouter van Ooijen <spamBeGonewouterspamBeGonespamvoti.nl> wrote:

{Quote hidden}

It is definitely not a white noise, Wouter :-)

Are you generating the source code as well as the documentation from a
pseudo code? Or maybe I am completely misunderstanding the way mkt works?

Thanks
Tamas
--
http://www.mcuhobby.com

2009\05\18@064748 by Wouter van Ooijen

face picon face
> Are you generating the source code as well as the documentation from a
> pseudo code? Or maybe I am completely misunderstanding the way mkt works?

Mostly the C or assembler source is in a string constant in the Python
source. In some cases it is tweaked a little (for instance with the
actual pins a HD44780 LCD is connected to). But there are cases where
the C or assembler source is generated by Python code. Examples are the
fixed-GPIO-pin-set and -clear macro's, and the interface to the chip's
peripheral registers.

The documentation is in nearly all cases a string constant, which is (as
far as possible) near the string constant for the code (or at least for
the C header).

The library-generating code is a class tree with the common parts in the
base class, and the more specialized parts in derived classes. The
documentation is in that same structure, with a hack that makes
specifying a documentation function in a derived class adding to the
original instead of replacing it.

I am not sure that last part is very clear. But you could try to read
mkt.py, it is only ~ 8500 lines ;)

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu

2009\05\21@110930 by Gerhard Fiedler

picon face
Wouter van Ooijen wrote:

{Quote hidden}

I'm not sure, but I don't think that Doxygen can handle multiple
languages in one file very well, so it won't extract it correctly if
written as above.

However, if you make the assembler code a comment in a C file (e.g. in
the header comment of the associated C function prototype), or put all
the assembler code in a separate file, you should be able to make this
work.

>> It really boils down to whether you want it to be with the source and
>> extracted (meaning Doxygen can be useful) or whether you want to
>> write it somewhere separately (meaning Doxygen can't be useful).
>
> In my case it's a bit complex: everything (C code, assembler code,
> documentation, and more) is in one Python source.

But you still generate C and assembly source files from that, over which
you can run Doxygen, right?

Gerhard

2009\05\21@125914 by Wouter van Ooijen

face picon face
> However, if you make the assembler code a comment in a C file (e.g. in
> the header comment of the associated C function prototype), or put all
> the assembler code in a separate file, you should be able to make this
> work.

Probably. But that would be (much) more work than the current
arrangement. Note that in assembler there is no header, parameter
passing is not visible in assembler, so you can't generate the asm
parameter passing from the asm code.

> But you still generate C and assembly source files from that, over which
> you can run Doxygen, right?

could do, yes.

--

Wouter van Ooijen

-- -------------------------------------------
Van Ooijen Technische Informatica: http://www.voti.nl
consultancy, development, PICmicro products
docent Hogeschool van Utrecht: http://www.voti.nl/hvu


'[OT] Doxygen'
2012\01\02@151107 by David VanHorn
picon face
I don't know what tag is appropriate, I'm looking for a "quick start"
for using Doxygen with ASM code.
I'll actually be doing AVR code, but I would be surprised if that matters.

Any pointers

2012\01\02@224233 by John Chung

picon face
If I recall me previous adventure on this..... Did not find any solution back 2-3 years ago. One of the main
issues for Doxygen was to identify the assembler directives. Each assembler had it's own funky way.... Imagine
this. Comments for a procedure..... from AVR to MASM.... Quite different.


Try this:
http://www.stack.nl/~dimitri/doxygen/faq.html (item 12)


John




________________________________
From: David VanHorn <TakeThisOuTmicrobrixEraseMEspamspam_OUTgmail.com>
To: Microcontroller discussion list - Public. <RemoveMEpiclistspamTakeThisOuTmit.edu> Sent: Tuesday, January 3, 2012 4:11 AM
Subject: [OT] Doxygen
I don't know what tag is appropriate, I'm looking for a "quick start"
for using Doxygen with ASM code.
I'll actually be doing AVR code, but I would be surprised if that matters.

Any pointers

More... (looser matching)
- Last day of these posts
- In 2012 , 2013 only
- Today
- New search...