No header files?

[BCS]

Hello aJ,

> "BCS" <none at anon.com> wrote in message
> news:a6268ffbb078cc2081280f1286 at 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.


>>> (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. The only time you should ever write a .di file by hand is as bindings 
for a non D codebase. .di files that describe something written in D should 
be auto generated. 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.

>> Some times I'd like exactly that but with better formatting.
>> 
> Seems like the exception rather than the common case. It depends on
> the coding style I guess. Certainly the STL header files are useless
> as any kind of documentation, that I grant you. But I'd consider that
> style of coding the exceptional case also.
> 

Even the best code editor I've ever seen doesn't come close to the readability 
that a halfway well done web page has. Try putting nice tables in your header 
files. Try adding clickable hyperlinks, always up to date tables of contents 
and indexes. A good tool will give you that and more for lest effort than 
it takes to keep the comment wrapping at 80 columns. 

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

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?