[Gambas-devel] generate documentation from source code? how

[Tobias Boege]

On Wed, 04 Sep 2013, Randall Morgan wrote:
> This subject came up a year or more ago. The issue is that for sme like me
> who travel a lot, you have no access to the documentation when you have no
> internet connection. It was discussed then that a solution such as what
> MSVS uses would be a good compromise. That is to allow the user to download
> a copy of the online docs and provide a local search. This was discussed
> but no development was ever done on this. I still think it is a good
> idea....
> 

May I step in (as politely as possible) and give another proposal (not a new
one, though):

I'm still convinced that from a developer's perspective it is much easier to
maintain documentation (of interface functions only!) in-code (like Lenz[*]
proposed when he mentioned doxygen).

At least for my personal workflow, the documentation would more likely be
 a) up to date; and
 b) actually existing.

In fact, components written in Gambas can be documented in their source code
and the documentation goes into the component's .info file. Consequently, I
wrote a bunch of scripts and a more complex program which extract docs from
C/C++ source files, format them and put them at the right places in the
component's .info file.

What we then have is the documentation of one repository snapshot in the
components' .info files.

The way this would not only solve my problem (I'd like to document my C
components in-code) but also your problem is this:

The IDE could surely be modified to read the installed components' .info
files for documentation. Since the .info files are generated from the
components' source code, the comments would (ideally!) directly match the
behaviour of the component at that stage.

A CheckBox could then toggle between:
 0) Use local .info files of current installation (no internet connection
    required); or
 1) Use online gambasdoc.org documentation which aims towards being
    relevant to trunk or the latest stable version.

Regarding the last point "relevant to trunk or the latest stable version",
we could have both since the documentation is then bound to a revision.

If there is a mechanism to import .info files into the gambasdoc.org server
(or it gets a cronjob to fetch updates from SVN trunk daily and rebuild the
trunk branch of documentation), the whole documentation could be generated
automatically.

>From a convenience point of view, this is what I would like to have.
Problems arise (AFAICS) for:
 a) translations; and
 b) server load (both hard disk and work load).

However, these are only relevant to the online documentation. We could
equally well leave the online documentation system as-is and focus on local
documentation in .info files...?

Anyways, there are still two things missing from my plan:
 a) the IDE cannot (to my knowledge) display comments in .info files (or it
    always prefers the online documentation); and
 b) there is no import functionality of .info files into the online
    documentation (may not be an issue, as I said).

I hope to not have bothered you with this again. I just don't remember to
have received any reaction on my previous posts about that.

Regards,
Tobi

[*] I'm really embarrassed: I don't know which of these words in your mail
    headers' From: lines is your first name. "Lenz" is the only one which
    has a meaning in my mother tongue :-) Please, let me know the proper
    name.