Proposal for Deimos documentation

[Jens Mueller]

1100110 wrote:
> On 03/20/2013 05:04 PM, Jens Mueller wrote:
> >Hi,
> >
> >I wrote some guidelines for writing a Deimos interface. It's still very
> >rough but it's a start. I'd like to add it to dlang.org to give
> >contributors better guidance, ultimately hoping to see more
> >contributions to Deimos.
> >Besides comments to improve my poor phrasing I'd especially seek to get
> >a complete list of recommendations to follow. Please comment.
> >
> >http://jkm.github.com/phobos/deimos.html
> >
> >Jens
> 
> """
> Each must follow the directory structure
> """
> 
> nitpick, maybe add a colon after that fragment?

Probably.

> """
> So far, each C header file was renamed to a D module. Next the
> contents of each module will be adjusted. In general following the
> advices from interfacing to c is recommended.
> 
> The D files should try to do as least modifications as possible to
> simplify updates of the C headers. This includes leaving comments
> intact. The copyright for the D files should match the one being
> used by the C header as they are derived work.
> ""
> 
> Maybe just a little more detail?

Where do you want more detail?

> Again a nitpick.  But I'd like to see a few "real world" examples of
> some of the trickier constructs mixed in.  Even if you left all the
> details to "interfacing to c", an example or two would clarify
> things IMO.

An example would help here. I was wondering whether anybody has
encountered a tricky example.

> """
> In particular,
> 
>     Replace C's include
> 
>     Each #include needs to have a corresponding import path.to.header;
> """
> 
> That has certainly not been my experience.  Often one D import will
> map to a couple of c includes.
> 
> I would suggest amending that statement.  It sounds too much like a
> hard rule(necessary to be considered for inclusion into Deimos) to
> me.  YMMV.

Do you have any examples where one import handles many C headers. I
haven't seen such cases and I wonder why you should need them.

Jens