Hello aJ,
"BCS" <[email protected]> wrote in message
news:[email protected]...
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?
