lurker wrote:
> Walter Bright Wrote:
> 
>> dsimcha wrote:
>>> == Quote from Adam Ruppe (destructionator@gmail.com)'s article
>>>> To me, the biggest appeal of ddoc is that it doesn't require markup to
>>>> give good enough results. It's almost mindless to use.
>>> Not only that, because it doesn't require markup, the docs look good as plain text
>>> comments, not just when processed into HTML.
>> That wasn't by accident :-). One of the explicit major goals of Ddoc was to not require any markup unless you are getting into more advanced use of it. Some of the design was compromised to make that work, but I think the results are worth it.
> 
> Unlike doxygen, Ddoc almost accepts plain english. It's not hard to see how much better designed Ddoc is *for D code*. A generic document generator can never support unit tests, contracts and so forth. I disagree with our ''retard'' completely.

A doxygen example from http://www.stack.nl/~dimitri/doxygen/docblocks.html :

      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Test()
       * @see ~Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);

The Ddoc equivalent:

      /**
       * a normal member taking two arguments and returning an integer value.
       * Params:
       *    a = an integer argument.
       *    s = a constant character pointer.
       * See_Also:
       *    Test()
       *    ~Test()
       *    testMeToo()
       *    publicVar()
       * Returns:
       *    The test results
       */
       int testMe(int a,const char *s);

Don Wrote:

> retard wrote:
> > Sat, 14 Aug 2010 20:24:33 -0500, Yao G. wrote:
> > 
> >> On Sat, 14 Aug 2010 20:20:49 -0500, Mike Parker <aldacron@gmail.com> wrote:
> >>
> >>
> >>> What prevents you from contributing to the frontend under its current license?
> >> Apparently he doesn't like butt-ugly frontends. That's the game breaker for him  :|
> > 
> > I'm using the same argumentation as Walter here. If I ever contributed code to the proprietary dmd, I would get sued by a group of lawyers when contributing code later to some other proprietary / open source compiler. Even seeing the code might taint my mind. Just like Walter refuses to read Tango's code to prevent license issues with Phobos.
> > 
> 
> 
> > Dmd's code also has several problems. I don't think it supports multi- core CPUs very well when parsing files. The other issues are: forward reference bugs, lack of a good internal garbage collector (CTFE & templates), not well documented (I know nearly nothing about compiler implementation).
> 
> Those things are all true, but not relevant to ddoc. The ddoc code is just doc.c, which is 58kB in size. You're quite right in saying that something much better could be produced in a week or so of work. The existing ddoc was made in about a week, and I've spent a couple of days fixing some of the most obvious bugs.
> 
> Now that most of the wrong-code and compiler error bugs are fixed, other
> stuff is becoming higher priority. Still, the fact that there are a
> thousand open compiler bugs, and only a couple of people working on the
> compiler is a pretty obvious limitation. Would be great if someone put a
>   concerted effort into ddoc for a

The advantage of ddoc is that it's simple. That makes it practical for us to use. No need to read long manuals, we can straight away write production quality documents with few macros. Even the idioms are very intuitive unlike @foo and @bar in Javadoc. I don't think the type signatures need better structure in the output. Walter usually foresees what is the most pragmatic solution. Seriously we should kick the retard out of here, he's only trolling with no useful arguments. Moderation.votes++

retard wrote:
>  - the markup/macro syntax is NIH new.

Not really. The macro syntax is copied from make. And it's utterly trivial.

I'd like to know how the macro system is inadequate for generating Latex, man, etc. format.

On Sun, 15 Aug 2010 16:27:57 -0500, Walter Bright <newshound2@digitalmars.com> wrote:

> I'd like to know how the macro system is inadequate for generating Latex, man, etc. format.

I'm attempting to generate DocBook 5.0 xml files using DDOC. I'll let you know what issues I find.


-- 
Yao G.

On 15.08.2010 23:27, Walter Bright wrote:
> retard wrote:
>>  - the markup/macro syntax is NIH new.
> 
> Not really. The macro syntax is copied from make. And it's utterly trivial.
> 
> I'd like to know how the macro system is inadequate for generating Latex, man, etc. format.

I think it's not a problem with the macro system, but with the few macros emitted by dmd: There are enough macros for the doc comments (DDOC_SUMMARY, DDOC_DESCRIPTION, ...) but not for the types. DDOC_DECL, DDOC_DECL_DD and DDOC_*_MEMBERS are just not enough to extract detailed information. This also puts quite some restrictions on the layout of the resulting documentation. In this case ddoc is very tied to html: These macros seem modeled directly after the DD DT DL html elements.

I tried to enhance the ddoc output over the last few weeks and it's not ready to be released yet, but for example this is the macro structure I've chosen for function definitions:

DDOC_FUNCTION
    DDOC_FUNCTION_HEADER_CONTAINER
        DDOC_FUNCTION_TEMPLATE_HEADER
        DDOC_FUNCTION_HEADER
            DDOC_TYPE_FUNCTION
                DDOC_FUNCTION_PREFIX
                DDOC_TYPE_MODIFIER
                DDOC_EXTRA_MODIFIER
                DDOC_TRUST
                DDOC_FUNCTION_RETURN_TYPE
                DDOC_FUNCTION_NAME
                DDOC_FUNCTION_PARAMETERS
                    DDOC_FUNCTION_LPAREN
                    DDOC_FUNCTION_PARAMETER
                        DDOC_FUNCTION_PARAMETER_STC (storage class)
                        DDOC_FUNCTION_PARAMETER_TYPE
                        DDOC_FUNCTION_PARAMETER_NAME
                        [DDOC_FUNCTION_PARAMETER_DEFAULT]
                        [DDOC_FUNCTION_COMMA]
                    [DDOC_FUNCTION_VARARGS]
                    DDOC_FUNCTION_RPAREN
            DDOC_DECLARATION_SEMICOLON
        DDOC_DITTO
            DDOC_FUNCTION_HEADER...
            DDOC_FUNCTION_TEMPLATE_HEADER...
            DDOC_TEMPLATE_HEADER
    DDOC_FUNCTION_DOC

One major aspect in my changes is that there should be no hardcoded
output: everything can be redefined through macros, though sane defaults
should be provided. Example:
DDOC_DECLARATION_SEMICOLON=;
DDOC_FUNCTION_VARARGS=...;
DDOC_FUNCTION_COMMA=,;

With more macros you can generate advanced looking documentation, for
example, this is what I currently have:
druntime docs: http://jpf.byethost10.com/druntime/doc/object.html
simple tests:
http://jpf.byethost10.com/demo/doc/ddoc/tests/simple/vars.html (druntime
2.047 in the right upper corner is still hardcoded...)

I also have xml output, but the xml ddoc file isn't complete yet (template support is missing) http://jpf.byethost10.com/demo_xml/ddoc/tests/simple/

And there's also a problem with phobos:in some cases the sources contain html. In other cases there are custom macros in modules which can only emit html(std.math, TABLE_SV, ...) and afaik you can't override module level macros with .ddoc files?
-- 
Johannes Pfau

Johannes Pfau wrote:
> On 15.08.2010 23:27, Walter Bright wrote:
>> retard wrote:
>>>  - the markup/macro syntax is NIH new.
>> Not really. The macro syntax is copied from make. And it's utterly trivial.
>>
>> I'd like to know how the macro system is inadequate for generating
>> Latex, man, etc. format.
> 
> I think it's not a problem with the macro system, but with the few
> macros emitted by dmd: There are enough macros for the doc comments
> (DDOC_SUMMARY, DDOC_DESCRIPTION, ...) but not for the types. DDOC_DECL,
> DDOC_DECL_DD and DDOC_*_MEMBERS are just not enough to extract detailed
> information.

Ok.

> This also puts quite some restrictions on the layout of the
> resulting documentation. In this case ddoc is very tied to html: These
> macros seem modeled directly after the DD DT DL html elements.

They are.


> I tried to enhance the ddoc output over the last few weeks and it's not
> ready to be released yet, but for example this is the macro structure
> I've chosen for function definitions:
> 
> DDOC_FUNCTION
>     DDOC_FUNCTION_HEADER_CONTAINER
>         DDOC_FUNCTION_TEMPLATE_HEADER
>         DDOC_FUNCTION_HEADER
>             DDOC_TYPE_FUNCTION
>                 DDOC_FUNCTION_PREFIX
>                 DDOC_TYPE_MODIFIER
>                 DDOC_EXTRA_MODIFIER
>                 DDOC_TRUST
>                 DDOC_FUNCTION_RETURN_TYPE
>                 DDOC_FUNCTION_NAME
>                 DDOC_FUNCTION_PARAMETERS
>                     DDOC_FUNCTION_LPAREN
>                     DDOC_FUNCTION_PARAMETER
>                         DDOC_FUNCTION_PARAMETER_STC (storage class)
>                         DDOC_FUNCTION_PARAMETER_TYPE
>                         DDOC_FUNCTION_PARAMETER_NAME
>                         [DDOC_FUNCTION_PARAMETER_DEFAULT]
>                         [DDOC_FUNCTION_COMMA]
>                     [DDOC_FUNCTION_VARARGS]
>                     DDOC_FUNCTION_RPAREN
>             DDOC_DECLARATION_SEMICOLON
>         DDOC_DITTO
>             DDOC_FUNCTION_HEADER...
>             DDOC_FUNCTION_TEMPLATE_HEADER...
>             DDOC_TEMPLATE_HEADER
>     DDOC_FUNCTION_DOC
> 
> One major aspect in my changes is that there should be no hardcoded
> output: everything can be redefined through macros, though sane defaults
> should be provided. Example:
> DDOC_DECLARATION_SEMICOLON=;
> DDOC_FUNCTION_VARARGS=...;
> DDOC_FUNCTION_COMMA=,;

This seems excessive.

> With more macros you can generate advanced looking documentation, for
> example, this is what I currently have:
> druntime docs: http://jpf.byethost10.com/druntime/doc/object.html
> simple tests:
> http://jpf.byethost10.com/demo/doc/ddoc/tests/simple/vars.html (druntime
> 2.047 in the right upper corner is still hardcoded...)
> 
> I also have xml output, but the xml ddoc file isn't complete yet
> (template support is missing)
> http://jpf.byethost10.com/demo_xml/ddoc/tests/simple/
> 
> And there's also a problem with phobos:in some cases the sources contain
> html. In other cases there are custom macros in modules which can only
> emit html(std.math, TABLE_SV, ...)

These should be fixed, but that's not a problem with Ddoc.

> and afaik you can't override module level macros with .ddoc files?

Right.

Hello Walter,

> Johannes Pfau wrote:
> 
>> On 15.08.2010 23:27, Walter Bright wrote:
>> 
>>> retard wrote:
>>> 
>>>> - the markup/macro syntax is NIH new.
>>>> 
>>> Not really. The macro syntax is copied from make. And it's utterly
>>> trivial.
>>> 
>>> I'd like to know how the macro system is inadequate for generating
>>> Latex, man, etc. format.
>>> 
>> I think it's not a problem with the macro system, but with the few
>> macros emitted by dmd: There are enough macros for the doc comments
>> (DDOC_SUMMARY, DDOC_DESCRIPTION, ...) but not for the types.
>> DDOC_DECL, DDOC_DECL_DD and DDOC_*_MEMBERS are just not enough to
>> extract detailed information.
>> 
> Ok.
> 
>> This also puts quite some restrictions on the layout of the
>> resulting documentation. In this case ddoc is very tied to html:
>> These
>> macros seem modeled directly after the DD DT DL html elements.
> They are.
> 
>> I tried to enhance the ddoc output over the last few weeks and it's
>> not ready to be released yet, but for example this is the macro
>> structure I've chosen for function definitions:
>> 
>> DDOC_FUNCTION
>> DDOC_FUNCTION_HEADER_CONTAINER
>> DDOC_FUNCTION_TEMPLATE_HEADER
>> DDOC_FUNCTION_HEADER
>> DDOC_TYPE_FUNCTION
>> DDOC_FUNCTION_PREFIX
>> DDOC_TYPE_MODIFIER
>> DDOC_EXTRA_MODIFIER
>> DDOC_TRUST
>> DDOC_FUNCTION_RETURN_TYPE
>> DDOC_FUNCTION_NAME
>> DDOC_FUNCTION_PARAMETERS
>> DDOC_FUNCTION_LPAREN
>> DDOC_FUNCTION_PARAMETER
>> DDOC_FUNCTION_PARAMETER_STC (storage class)
>> DDOC_FUNCTION_PARAMETER_TYPE
>> DDOC_FUNCTION_PARAMETER_NAME
>> [DDOC_FUNCTION_PARAMETER_DEFAULT]
>> [DDOC_FUNCTION_COMMA]
>> [DDOC_FUNCTION_VARARGS]
>> DDOC_FUNCTION_RPAREN
>> DDOC_DECLARATION_SEMICOLON
>> DDOC_DITTO
>> DDOC_FUNCTION_HEADER...
>> DDOC_FUNCTION_TEMPLATE_HEADER...
>> DDOC_TEMPLATE_HEADER
>> DDOC_FUNCTION_DOC
>> One major aspect in my changes is that there should be no hardcoded
>> output: everything can be redefined through macros, though sane
>> defaults
>> should be provided. Example:
>> DDOC_DECLARATION_SEMICOLON=;
>> DDOC_FUNCTION_VARARGS=...;
>> DDOC_FUNCTION_COMMA=,;
> This seems excessive.
> 

Unless you are setting up a new output format, you will never see them. In that light, it doesn't seem excessive to me.

-- 
... <IXOYE><

BCS wrote:
>>> One major aspect in my changes is that there should be no hardcoded
>>> output: everything can be redefined through macros, though sane
>>> defaults
>>> should be provided. Example:
>>> DDOC_DECLARATION_SEMICOLON=;
>>> DDOC_FUNCTION_VARARGS=...;
>>> DDOC_FUNCTION_COMMA=,;
>> This seems excessive.
>>
> 
> Unless you are setting up a new output format, you will never see them. In that light, it doesn't seem excessive to me.

Adding features because one can isn't good enough. One should only add features if they fill a real need. I don't see a point to things like a macro for a ;.

Walter Bright, el 15 de agosto a las 19:53 me escribiste:
> BCS wrote:
> >>>One major aspect in my changes is that there should be no hardcoded
> >>>output: everything can be redefined through macros, though sane
> >>>defaults
> >>>should be provided. Example:
> >>>DDOC_DECLARATION_SEMICOLON=;
> >>>DDOC_FUNCTION_VARARGS=...;
> >>>DDOC_FUNCTION_COMMA=,;
> >>This seems excessive.
> >>
> >
> >Unless you are setting up a new output format, you will never see them. In that light, it doesn't seem excessive to me.
> 
> Adding features because one can isn't good enough. One should only add features if they fill a real need. I don't see a point to things like a macro for a ;.

What about < and &? =)

-- 
Leandro Lucarella (AKA luca)                     http://llucax.com.ar/
----------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------
Borrowing money from a friend is like having sex. It just completely changes
the relationship.
	-- George Constanza

On 16.08.2010 04:53, Walter Bright wrote:
> BCS wrote:
>>>> One major aspect in my changes is that there should be no hardcoded
>>>> output: everything can be redefined through macros, though sane
>>>> defaults
>>>> should be provided. Example:
>>>> DDOC_DECLARATION_SEMICOLON=;
>>>> DDOC_FUNCTION_VARARGS=...;
>>>> DDOC_FUNCTION_COMMA=,;
>>> This seems excessive.
>>>
>>
>> Unless you are setting up a new output format, you will never see them. In that light, it doesn't seem excessive to me.
> 
> Adding features because one can isn't good enough. One should only add features if they fill a real need. I don't see a point to things like a macro for a ;.
The macro for the ; is needed because you might want to strip it out in the final output. With hardcoded ; this is not easily doable. If you look at the posted examples you will see that I hide the ; for most types. This is the only way to achieve something like <span class="ddoc_semicolon">;</span> which now allows all kinds of css stuff. The xml output for example completely ignores semicolons and commas, because they don't make sense there.

<returns>void</returns>
<name>testFunction</name>
<parameters>
  <parameter>
    <type>int</type>
    <name>i</name>
  </parameter>
<parameters>...

Also consider that all macros have sane defaults. No one is required to redefine them if it's not needed. In fact most macros default to a simple $0 and unless you redefine these you'll never come across them.

I agree though that there are lots of macros, maybe too many. But it's hard to find the point between too few and too many. This remembers me, that there is another limitation with the macro system. Consider for example:

DDOC_CLASS
    DDOC_PROTECTION

DDOC_FUNTION
    DDOC_PROTECTION

In the DDOC_PROTECTION macro you never know whether this is the
protection for the function or for the class. If you need different
output for DDOC_PROTECTION depending on that, you'll have to define
DDOC_CLASS_PROTECTION and DDOC_FUNCTION_PROTECTION or you have to
generate xml first
<ddoc_class><ddoc_protetion>private</ddoc_protetion></ddoc_class> and
process this xml further, because with xml you can extract the parent
elements.
I know this is by design, and it's not a huge problem. But it means you
need even more macros if you want to make rich output possible without a
custom post processor.

I know that the phobos problem is not directly a problem of ddoc. I just mentioned it because it also makes generating documentation for other formats harder. These phobos macros should maybe be moved to the std.ddoc file. But then we have custom phobos macros which must be redefined for generating a different output format and if every project defines there own macros like that, making .ddoc files to output to different formats soon becomes a mess. I agree that macros to output tables etc are needed though. But it's important that not every project defines it's own table macros.

And one more problem, though not directly related to the macro system: If one really documented code in a WYSIWYG way and would not think he might be generating html, he could use <,> and &. This would definitely break html, which means you must make assumptions about the final output format in the documentation or you might break it.

-- 
Johannes Pfau