Re: Why a slash and not an @ symbol? (and other general questions)

Thanks so much for the quick reply.

The only reason I would think to use the @ symbol is to make it more
familiar and approachable by future developers familiar with languages
like Java where that is the common symbol used.

With the ILEDoc output format, do you already have a solution for making
it a searchable via keywords and/or content?

Thanks,
Robert Newton
Estes IT
System Architect
804-353-1900 x2256
rnewton@xxxxxxxxxxxxxxxxx



From:
Mihael Schmidt <mihael@xxxxxxxxxxxxxx>
To:
ILEDocs <iledocs@xxxxxxxxxxxx>
Date:
06/06/2011 02:59 PM
Subject:
Re: [IleDocs] Why a slash and not an @ symbol? (and other general
questions)
Sent by:
iledocs-bounces@xxxxxxxxxxxx



On 06.06.2011 15:39, RNewton@xxxxxxxxxxxxxxxxx wrote:

Hi,

I am starting to research RPG documentation comment parsers to consider
implementing in our shop. I have a few questions about your project I

hope

you can answer.

I'm curious about the reasoning behind choosing to use a slash instead

of

an @ as the starting character of the keywords?
Is it possible to configure the engine to look for @ characters instead

of

a slash?
Are custom keywords configurable via a control file or does the source
code have to be changed and recompiled?

There is no real reasoning behind the backslash. I just started to have
a look at doxygen for an RPG code documentation tool. The default for C
style documentation is \ or @. So I took the \.

All tags (like \brief) can be configured in the file ILEDCONF.

Though you cannot just add a tag there. That would have to be added in
the code also.

RPGDoc at Sourceforge: That project doesn't seem to be alive in any way.

RPGLEDoc: Never worked with it. My point of view: It doesn't seem to be
very usable (too many clicks, poor overview over modules/procedures,
poor view on how to use a procedure/API). I can't think of anybody using
that in real life. Seems to me like a pet project. But that is a very
typical project for the RPG community. It does things differently like
all other documentation systems (and I don't think that the other are
doing it wrong).

But you can compare those two by yourself:

RPGLEDoc: http://www.systemideveloper.com/demoDoc/vw000a.php

ILEDocs: http://iledocs.sourceforge.net/docs/


Other example from doxygen to get an overview how others do it:

http://xerces.apache.org/xerces-c/apiDocs-3/classes.html

Javadocs: http://download.oracle.com/javase/1.5.0/docs/api/index.html


In this case we need to be more mainstream because the mainstream has
gathered experiences in this topic for decades.

All just my personal opinion.

Mihael

Also, what are some of the key differences (if you have had experience
with each) between ILEDocs and the others out there such as RPGDoc (
http://sourceforge.net/projects/rpgdoc/) and RPGLEDOC (
http://www.systemideveloper.com/downloadRPGLEDOC.html).

Thanks,
Robert Newton
Estes IT
System Architect
804-353-1900 x2256
rnewton@xxxxxxxxxxxxxxxxx


This communication and any transmitted documents are intended to be
confidential. If there is a problem with this transmission, please

contact

the sender. If the reader of this message is not the intended recipient,

or the employee or agent responsible to deliver it to the intended
recipient, you are hereby notified that any dissemination, distribution

or

copying of this communication is strictly prohibited.