• Jason House <jason.james.house gmail.com> Oct 21 2009
• "AJ" <aj nospam.net> Oct 21 2009
• Walter Bright <newshound1 digitalmars.com> Oct 21 2009
• "AJ" <aj nospam.net> Oct 21 2009
• Bill Baxter <wbaxter gmail.com> Oct 21 2009
• "AJ" <aj nospam.net> Oct 21 2009
• BCS <none anon.com> Oct 22 2009
• =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> Oct 23 2009
• BCS <none anon.com> Oct 27 2009

Jason House <jason.james.house gmail.com> writes:

AJ Wrote:

 
 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message 
 news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that another
 developer can use without exposing the implementation?


 try dmd -H.

 .di files are D header files, basically used for the reason you specify.


 OK, so header files can be generated. The thing is though, when I am 
 designing at the code level, I start with the declarations (such as class 
 data members and methods) and do the implementation (or one can hand it off 
 to someone else) afterwards. That serves as the "blue print" for further 
 development and remains as first level of documentation as well. Working 
 with just "implementation files" seems to be putting the cart before the 
 horse. While eliminating something unnecessary is something to strive for, I 
 don't think header files are unnecessary in the development process (i.e., I 
 don't think that relegating them to just the situation given with my OP is 
 good, exactly for the reasons of usefullness I gave). 
 
 


I think you keep a very structured development style that few share. Nothing
stops you from writing a header-file-like .d file and then hand it off for
someone to fill in the methods, etc... A good IDE can also make a .d file look
like a header file. Personally, I like colocating documentation with
implementation and using tools (such as dmd) to extract higher level
documentation. 

"AJ" <aj nospam.net> writes:

"Jason House" <jason.james.house gmail.com> wrote in message 
news:hbo2ih$2oii$1 digitalmars.com...
 AJ Wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that 
 another
 developer can use without exposing the implementation?


 try dmd -H.

 .di files are D header files, basically used for the reason you 
 specify.


 OK, so header files can be generated. The thing is though, when I am
 designing at the code level, I start with the declarations (such as class
 data members and methods) and do the implementation (or one can hand it 
 off
 to someone else) afterwards. That serves as the "blue print" for further
 development and remains as first level of documentation as well. Working
 with just "implementation files" seems to be putting the cart before the
 horse. While eliminating something unnecessary is something to strive 
 for, I
 don't think header files are unnecessary in the development process 
 (i.e., I
 don't think that relegating them to just the situation given with my OP 
 is
 good, exactly for the reasons of usefullness I gave).


 I think you keep a very structured development style that few share.
 Nothing stops you from writing a header-file-like .d file and then hand it
 off for someone to fill in the methods, etc...


Would I have to use a dmd-generated one to distribute to users of my library 
though? Are generated .di files something different or more than what I'd 
write in a C/C++ .h?

Walter Bright <newshound1 digitalmars.com> writes:

AJ wrote:
 Would I have to use a dmd-generated one to distribute to users of my library 
 though?


No, you can just use the library source code (like Phobos does) or use a 
hand-generated one.

 Are generated .di files something different or more than what I'd 
 write in a C/C++ .h?


They're roughly equivalent, except that they can be automatically generated.

"AJ" <aj nospam.net> writes:

"Walter Bright" <newshound1 digitalmars.com> wrote in message 
news:hbo7ii$316k$3 digitalmars.com...
 AJ wrote:
 Would I have to use a dmd-generated one to distribute to users of my 
 library though?


 No, you can just use the library source code (like Phobos does) or use a 
 hand-generated one.


OK.

 Are generated .di files something different or more than what I'd write 
 in a C/C++ .h?


 They're roughly equivalent, except that they can be automatically 
 generated.


OK. "roughly"? 

Bill Baxter <wbaxter gmail.com> writes:

On Wed, Oct 21, 2009 at 4:56 PM, AJ <aj nospam.net> wrote:
 "Jason House" <jason.james.house gmail.com> wrote in message
 news:hbo2ih$2oii$1 digitalmars.com...
 AJ Wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that
 another
 developer can use without exposing the implementation?


 try dmd -H.

 .di files are D header files, basically used for the reason you
 specify.


 OK, so header files can be generated. The thing is though, when I am
 designing at the code level, I start with the declarations (such as class
 data members and methods) and do the implementation (or one can hand it
 off
 to someone else) afterwards. That serves as the "blue print" for further
 development and remains as first level of documentation as well. Working
 with just "implementation files" seems to be putting the cart before the
 horse. While eliminating something unnecessary is something to strive
 for, I
 don't think header files are unnecessary in the development process
 (i.e., I
 don't think that relegating them to just the situation given with my OP
 is
 good, exactly for the reasons of usefullness I gave).


 I think you keep a very structured development style that few share.
 Nothing stops you from writing a header-file-like .d file and then hand it
 off for someone to fill in the methods, etc...


 Would I have to use a dmd-generated one to distribute to users of my library
 though? Are generated .di files something different or more than what I'd
 write in a C/C++ .h?


The generated ones lack indentation and comments.
They're not really intended for human consumption, according to Walter.

So if you want to ship headers as a form of documentation for your
library, you may want to find another way.
This -json output feature recently added to DMD sounded like it might
be a step in the right direction.  That should make it easier for 3rd
parties to write a more flexible documentation generation tool.

--bb

"AJ" <aj nospam.net> writes:

"Bill Baxter" <wbaxter gmail.com> wrote in message 
news:mailman.225.1256170012.20261.digitalmars-d puremagic.com...
 On Wed, Oct 21, 2009 at 4:56 PM, AJ <aj nospam.net> wrote:
 "Jason House" <jason.james.house gmail.com> wrote in message
 news:hbo2ih$2oii$1 digitalmars.com...
 AJ Wrote:

 "Steven Schveighoffer" <schveiguy yahoo.com> wrote in message
 news:op.u157hfkveav7ka localhost.localdomain...
 On Wed, 21 Oct 2009 17:59:52 -0400, AJ <aj nospam.net> wrote:

 Since D has no header files, how does one create "a library" that
 another
 developer can use without exposing the implementation?


 try dmd -H.

 .di files are D header files, basically used for the reason you
 specify.


 OK, so header files can be generated. The thing is though, when I am
 designing at the code level, I start with the declarations (such as 
 class
 data members and methods) and do the implementation (or one can hand it
 off
 to someone else) afterwards. That serves as the "blue print" for 
 further
 development and remains as first level of documentation as well. 
 Working
 with just "implementation files" seems to be putting the cart before 
 the
 horse. While eliminating something unnecessary is something to strive
 for, I
 don't think header files are unnecessary in the development process
 (i.e., I
 don't think that relegating them to just the situation given with my OP
 is
 good, exactly for the reasons of usefullness I gave).


 I think you keep a very structured development style that few share.
 Nothing stops you from writing a header-file-like .d file and then hand 
 it
 off for someone to fill in the methods, etc...


 Would I have to use a dmd-generated one to distribute to users of my 
 library
 though? Are generated .di files something different or more than what I'd
 write in a C/C++ .h?


 The generated ones lack indentation and comments.
 They're not really intended for human consumption, according to Walter.


OK, then they don't fulfill my requirements of "header files". Not to worry 
though, I just won't use that style of programming with D if I use it.

 So if you want to ship headers as a form of documentation for your
 library, you may want to find another way.


Yes: do it the traditional way as in C/C++.

 This -json output feature recently added to DMD sounded like it might
 be a step in the right direction.  That should make it easier for 3rd
 parties to write a more flexible documentation generation tool.

BCS <none anon.com> writes:

Hello aJ,

 "Bill Baxter" <wbaxter gmail.com> wrote in message
 news:mailman.225.1256170012.20261.digitalmars-d puremagic.com...
 
 So if you want to ship headers as a form of documentation for your
 library, you may want to find another way.
 


 


You keep refuring to the header files as documentation but I can't remember 
that last time I looked at someone else's .h file where I didn't already 
consider something to be broken. If the only source of info on how to use 
a library is the header files, I'll just use a differnt lib or write my own, 
because IMHO they make for really bad documentation. 

=?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:

BCS wrote:

 So if you want to ship headers as a form of documentation for your
 library, you may want to find another way.




 You keep refuring to the header files as documentation but I can't 
 remember that last time I looked at someone else's .h file where I 
 didn't already consider something to be broken. If the only source of 
 info on how to use a library is the header files, I'll just use a 
 differnt lib or write my own, because IMHO they make for really bad 
 documentation.


HeaderDoc isn't that bad (like when compared to JavaDoc or something)

http://developer.apple.com/opensource/tools/headerdoc.html

For D (or alternatively) one could use Doxygen, or the built-in ddoc.

Something like http://wxd.sourceforge.net/api/index.html

--anders

BCS <none anon.com> writes:

Hello Anders,

 BCS wrote:
 
 So if you want to ship headers as a form of documentation for your
 library, you may want to find another way.
 


 


 remember that last time I looked at someone else's .h file where I
 didn't already consider something to be broken. If the only source of
 info on how to use a library is the header files, I'll just use a
 differnt lib or write my own, because IMHO they make for really bad
 documentation.
 


 
 http://developer.apple.com/opensource/tools/headerdoc.html
 
 For D (or alternatively) one could use Doxygen, or the built-in ddoc.
 
 Something like http://wxd.sourceforge.net/api/index.html


I have no problems with the header files being the source for the documentation 
files. What I'm saying is a bad thing is when the header file IS the
documentation 
file.