"BCS" <n...@anon.com> wrote in message news:a6268ffbc118cc2111f7478...@news.digitalmars.com... > Hello aJ, > >> "BCS" <n...@anon.com> wrote in message >> news:a6268ffbb078cc2081280f1...@news.digitalmars.com... >> >>> I will hold that the full source or "webpage like" documentation will >>> do better in all cases than a header file. The first for where the >>> details matter and the second for all other cases because it can >>> contain anything the header can and is not bound by language >>> constraints. >>> >> We'll have to agree to disagree on that. Eliminating headers but >> requiring a "webpage", is "robbing Peter to pay Paul". >> > > Note that I'm assuming the avalability of a tool (like DMD has) to > automaticly generate sutch a document.
Doesn't fit my development process. > > >>>> (1) is "working at a higher level (designing vs. implenting) and >>>> perhaps even separating much of the design work from the >>>> implementation work (i.e., separate individuals or teams working on >>>> one or the other). (2) eliminates the need for secondary >>>> documentation (for well-designed code). I think of secondary >>>> documentation as the detailed description of how something works. >>>> Prior to consulting such, I'd want to know "what" something is, and >>>> something like a class declaration gives me that information >>>> immediately, without reading paragraphs of text. For example, you >>>> can describe "car" to me, but it would be much easier to just show >>>> me one. >>>> >>> As said above, you can declare a class without implementing it in the >>> current system as well as progamaticly extract what you are asking >>> for in whatever format you want. >>> >> So, it would appear, that if I am to write in D, I will be writing .di >> files just like I write .h files in C/C++. OK. >> > > Nope. Uh huh!! >The only time you should ever write a .di file by hand is as bindings for a >non D codebase. Now we're going in circles (in this thread). It has been said that I don't have to change my development process to use D (I use C++ now). > .di files that describe something written in D should be auto generated. You say tomatoe, I say tomato. > If you want to sketch out an interface and now and implement it later, I'd > expect both to be done in a .d file (just replace the function bodies with > ';') > >>>> What more do you need to know usually? >>> Some times I'd like some comments/verbiage. >>> >> Well of course header files will have comments. The thing is though, >> tomes of documentation are not necessary you have header files. And >> what are the chances that the documentation will be in synch with the >> code if the documentation is external? Much better chance of that if >> the header file IS the documentation and the code is crafted such that >> it needs very little doc. >> > > Or even better, the code file has both the documentation source and the > implementation source and you have a tool that can use that one file to > generate the final documentation in a nicer format. > > BTW, the same argument for not having the documentation be in a different > file from the header also holds for not having the interface definition be > in a different file from the implementation. > No need to try to convince me to adopt a new development process. Save your breath. > >>> The point is that if you want to start by coding that up, you can >>> with the current system. >>> >> OK, noted. If I ever write any D, that will be my preferred style. >> >>> If you have a full program and you want that, you can generate it >>> from the full program with the current system. >>> >> I won't be using that feature. >> >>> I have yet to see anything you have asked for that the current system >>> can't give you. It just doesn't give it to you in exactly the same >>> way C does. >>> >> Apparently it does! No? > > It does what? Give it in exactly the same way. (Allows me to develop headers first and potentially hand those off to someone else to flesh out). > > C generally uses hand written interface and implementation files. D has > either; a hand written implementation file and a auto generated interface > file, only the implementation file or a hand written interface file and a > non-D implementation. > > Doesn't look like what C does or am I totally lost on what you are looking > for? Now I'm unsure about .di files. Are they like .h files or not? Does D have classes that are like C++ classes that can be declared in .di files and are not just "interfaces"? What is the definition of "interface" in D? I think in C++ isms and generally accepted OO terminology for that kind of thing, but I don't know D-isms at this time (for the most part).