Proposal for Deimos documentation

[1100110]

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?

"""
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?
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.


"""
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.