www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - lint for D

reply "Bruce Adams" <tortoise_74 yeah.who.co.uk> writes:
Hi all,
        Alas this is not an announcement. It should be relatively easy to  
knock up a few noddy scripts that can detect some kinds
of potential problem. I occasionally find myself doing this for coding  
standard related things. The unused variable warning thing
would seem to be a good start. How about writing a lint tool that starts  
with that as its only requirement and going forward from
there? Unfortunately I don't have much time to work with D at the moment  
or I'd cobble something together. Maybe if the community
is still waiting in 6 months time.
   My biggest worry for linting D is CTFE and especially mixins. You have  
the same problem here as with macros in C. You cannot spot
potential problems until you have pre-processed the code. This is going to  
make it hard for any lint to get a toehold on D without
having a fully fledged front-end to start with. We already have several of  
these to hand. Even so I'm sure there are things that
could be picked up with a few clever greps and filters just to get the  
ball rolling.
May I further suggest that any potential writers of such tools take a look  
at Gimpel lint for some ideas on how to do lint comments.
In D it might be worth thinking about using custom pragmas instead (or as  
well) as an alternative to polluting the comment namespace
(which will soon get crowded with Doxygen and whatever else you want to  
throw in).
Any thoughts?

Regards,

Bruce.
Jul 09 2008
next sibling parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
Bruce Adams a écrit :

 
 Hi all,
        Alas this is not an announcement. It should be relatively easy to 
 knock up a few noddy scripts that can detect some kinds
 of potential problem.


It should be relatively easy to write a plugin for Descent to do that. 
Something similar to FindBugs for Java ( 
http://findbugs.sourceforge.net/ ). Given a source file, you can ask 
Descent for it's AST with complete type resolution. You can apply the 
visitor pattern, which is supported by the AST nodes. You can store in a 
list which variables are declared, and then if they are used in a 
function or are written too, you eliminate them. The remaining entries 
in the list are the unused variables. It's a little harder for 
class/struct members, but it's still relatively easy.

It is both helpful for a developer and for Descent, because the code 
that support that is kind of finished, but it isn't tested much (it's 
only used in highlighting code, which seems to work fine). Of course I 
could do that, but atm I'm adding support for D2, plus it would be 
interesting if anyone else could join the project.
Jul 09 2008
parent reply "Bruce Adams" <tortoise_74 yeah.who.co.uk> writes:
On Thu, 10 Jul 2008 02:44:07 +0100, Ary Borenszweig <ary esperanto.org.ar>  
wrote:


 Bruce Adams a écrit :

  Hi all,
        Alas this is not an announcement. It should be relatively easy  
 to knock up a few noddy scripts that can detect some kinds
 of potential problem.


 It should be relatively easy to write a plugin for Descent to do that.  
 Something similar to FindBugs for Java (  
 http://findbugs.sourceforge.net/ ). Given a source file, you can ask  
 Descent for it's AST with complete type resolution. You can apply the  
 visitor pattern, which is supported by the AST nodes. You can store in a  
 list which variables are declared, and then if they are used in a  
 function or are written too, you eliminate them. The remaining entries  
 in the list are the unused variables. It's a little harder for  
 class/struct members, but it's still relatively easy.

 It is both helpful for a developer and for Descent, because the code  
 that support that is kind of finished, but it isn't tested much (it's  
 only used in highlighting code, which seems to work fine). Of course I  
 could do that, but atm I'm adding support for D2, plus it would be  
 interesting if anyone else could join the project.


This is a pet hate of mine. Tool should not be plug-ins for IDEs.
Not unless there is a way to run them as stand alone tools in your
automated build process when the IDE is not running.
I much prefer the idea of a clever command line tool. You can then have a  
plug-in
that wraps it. I realise this means you can't take advantage of all the  
IDEs
features but to me that is evidence that those features belong in a shared  
library
and not as part of the IDE itself. Eclipse is notorious for this.
That said, if your IDE has a way to run plug-ins without loading the  
entire envrionment
then it can still act like a command line tool and be built into whatever  
build scripts
you desire.
I still think the separation is important. Otherwise you may update your  
plug-in to do
something clever like jump to line X and open the help for it which will  
make the command
line equivalent choke. Much better if the IDE groks the output of the tool  
and its
in a compiler friendly format giving the file and line numbers.

Regards,

Bruce.
Jul 10 2008
parent reply Ary Borenszweig <ary esperanto.org.ar> writes:
Bruce Adams a écrit :

 On Thu, 10 Jul 2008 02:44:07 +0100, Ary Borenszweig 
 <ary esperanto.org.ar> wrote:
 

 Bruce Adams a écrit :

  Hi all,
        Alas this is not an announcement. It should be relatively easy 
 to knock up a few noddy scripts that can detect some kinds
 of potential problem.


 It should be relatively easy to write a plugin for Descent to do that. 
 Something similar to FindBugs for Java ( 
 http://findbugs.sourceforge.net/ ). Given a source file, you can ask 
 Descent for it's AST with complete type resolution. You can apply the 
 visitor pattern, which is supported by the AST nodes. You can store in 
 a list which variables are declared, and then if they are used in a 
 function or are written too, you eliminate them. The remaining entries 
 in the list are the unused variables. It's a little harder for 
 class/struct members, but it's still relatively easy.

 It is both helpful for a developer and for Descent, because the code 
 that support that is kind of finished, but it isn't tested much (it's 
 only used in highlighting code, which seems to work fine). Of course I 
 could do that, but atm I'm adding support for D2, plus it would be 
 interesting if anyone else could join the project.


 
 This is a pet hate of mine. Tool should not be plug-ins for IDEs.


The thing is, you write all the code, then, from time to time you run 
that lint tool. You get 200 warnings. Will you want to correct them? 
Come on, those are just warnings, and 200 of them! Maybe there's no 
time, maybe it doesn't worth the effort. And you'd have to open up the 
code, remember what it was about, understanding it...

In an IDE: you finish writing a method. Even while writing at it, you 
get the warnings. It's easy to correct, you are there, staring at the 
code. It won't take your time, you have the code in your head, you know 
why the warning is there and how to remove it. And you do it.

Just my thought...
Jul 10 2008
next sibling parent Markus Koskimies <markus reaaliaika.net> writes:
On Thu, 10 Jul 2008 07:53:54 -0300, Ary Borenszweig wrote:


 The thing is, you write all the code, then, from time to time you run
 that lint tool. You get 200 warnings. Will you want to correct them?
 Come on, those are just warnings, and 200 of them! Maybe there's no
 time, maybe it doesn't worth the effort. And you'd have to open up the
 code, remember what it was about, understanding it...


You are exactly right. That's why the checkings should be always used in 
a build chain, and it should not allow the build to complete, if there 
are warnings.


 In an IDE: you finish writing a method. Even while writing at it, you
 get the warnings. It's easy to correct, you are there, staring at the
 code. It won't take your time, you have the code in your head, you know
 why the warning is there and how to remove it. And you do it.


IDE plugin of course makes things easier, just like configuring your 
favorite editor to execute compiler by pressing a key. Although I'm not 
using IDE, I constantly compile the code (make) while editing it.
Jul 10 2008
prev sibling next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"Ary Borenszweig" <ary esperanto.org.ar> wrote in message 
news:g54po3$2s7h$1 digitalmars.com...

 Bruce Adams a écrit :

 On Thu, 10 Jul 2008 02:44:07 +0100, Ary Borenszweig 
 <ary esperanto.org.ar> wrote:


 Bruce Adams a écrit :

  Hi all,
        Alas this is not an announcement. It should be relatively easy 
 to knock up a few noddy scripts that can detect some kinds
 of potential problem.


 It should be relatively easy to write a plugin for Descent to do that. 
 Something similar to FindBugs for Java ( 
 http://findbugs.sourceforge.net/ ). Given a source file, you can ask 
 Descent for it's AST with complete type resolution. You can apply the 
 visitor pattern, which is supported by the AST nodes. You can store in a 
 list which variables are declared, and then if they are used in a 
 function or are written too, you eliminate them. The remaining entries 
 in the list are the unused variables. It's a little harder for 
 class/struct members, but it's still relatively easy.

 It is both helpful for a developer and for Descent, because the code 
 that support that is kind of finished, but it isn't tested much (it's 
 only used in highlighting code, which seems to work fine). Of course I 
 could do that, but atm I'm adding support for D2, plus it would be 
 interesting if anyone else could join the project.


 This is a pet hate of mine. Tool should not be plug-ins for IDEs.


 The thing is, you write all the code, then, from time to time you run that 
 lint tool. You get 200 warnings. Will you want to correct them? Come on, 
 those are just warnings, and 200 of them! Maybe there's no time, maybe it 
 doesn't worth the effort. And you'd have to open up the code, remember 
 what it was about, understanding it...


Problem goes away with a thing called discipline. It's been about 10 years 
since I've allowed my warning counts to get anywhere near that big, and even 
if it did suddenly happen to me today, there's not a chance I'd allow myself 
to be intimidated by it.


 In an IDE: you finish writing a method. Even while writing at it, you get 
 the warnings. It's easy to correct, you are there, staring at the code. It 
 won't take your time, you have the code in your head, you know why the 
 warning is there and how to remove it. And you do it.


I agree a tool like this should be integrated/integratable into an IDE. BUT, 
there should at least be a command-line version so that you aren't married 
to a specific IDE (or any IDE at all if you happen to be that kind of 
person). I think the eclipse plugin that was proposed sounds great *as a 
start* because, from the sound of it (I wouldn't know, I don't like to use 
Eclipse) it would allow *something* to be out there much more quickly than 
starting a new command-line tool and getting it up to speed. Maybe it could 
even be used for prototyping diagnostic ideas. BUT, I would consider a 
command-line version (even if it were built into the compiler - though I'm 
sure that won't ever happen) to be essential, and something to eventually 
replace (or at least exist side-by-side) the interim Eclipse-based solution.


 Just my thought...
Jul 10 2008
parent reply Robert Fraser <fraserofthenight gmail.com> writes:
Nick Sabalausky Wrote:


 "Ary Borenszweig" <ary esperanto.org.ar> wrote in message 
 news:g54po3$2s7h$1 digitalmars.com...

 Bruce Adams a écrit :

 On Thu, 10 Jul 2008 02:44:07 +0100, Ary Borenszweig 
 <ary esperanto.org.ar> wrote:


 Bruce Adams a écrit :

  Hi all,
        Alas this is not an announcement. It should be relatively easy 
 to knock up a few noddy scripts that can detect some kinds
 of potential problem.


 It should be relatively easy to write a plugin for Descent to do that. 
 Something similar to FindBugs for Java ( 
 http://findbugs.sourceforge.net/ ). Given a source file, you can ask 
 Descent for it's AST with complete type resolution. You can apply the 
 visitor pattern, which is supported by the AST nodes. You can store in a 
 list which variables are declared, and then if they are used in a 
 function or are written too, you eliminate them. The remaining entries 
 in the list are the unused variables. It's a little harder for 
 class/struct members, but it's still relatively easy.

 It is both helpful for a developer and for Descent, because the code 
 that support that is kind of finished, but it isn't tested much (it's 
 only used in highlighting code, which seems to work fine). Of course I 
 could do that, but atm I'm adding support for D2, plus it would be 
 interesting if anyone else could join the project.


 This is a pet hate of mine. Tool should not be plug-ins for IDEs.


 The thing is, you write all the code, then, from time to time you run that 
 lint tool. You get 200 warnings. Will you want to correct them? Come on, 
 those are just warnings, and 200 of them! Maybe there's no time, maybe it 
 doesn't worth the effort. And you'd have to open up the code, remember 
 what it was about, understanding it...


 
 Problem goes away with a thing called discipline. It's been about 10 years 
 since I've allowed my warning counts to get anywhere near that big, and even 
 if it did suddenly happen to me today, there's not a chance I'd allow myself 
 to be intimidated by it.
 

 In an IDE: you finish writing a method. Even while writing at it, you get 
 the warnings. It's easy to correct, you are there, staring at the code. It 
 won't take your time, you have the code in your head, you know why the 
 warning is there and how to remove it. And you do it.


 
 I agree a tool like this should be integrated/integratable into an IDE. BUT, 
 there should at least be a command-line version so that you aren't married 
 to a specific IDE (or any IDE at all if you happen to be that kind of 
 person). I think the eclipse plugin that was proposed sounds great *as a 
 start* because, from the sound of it (I wouldn't know, I don't like to use 
 Eclipse) it would allow *something* to be out there much more quickly than 
 starting a new command-line tool and getting it up to speed. Maybe it could 
 even be used for prototyping diagnostic ideas. BUT, I would consider a 
 command-line version (even if it were built into the compiler - though I'm 
 sure that won't ever happen) to be essential, and something to eventually 
 replace (or at least exist side-by-side) the interim Eclipse-based solution.
 

 Just my thought...




What Ary was saying is that an IDE tool can do the checks while you type.
A command-line tool can't do that. And wrapping a GUI around a different
process is a non-trivial task.

Both tool types have their uses in different situations.
Jul 10 2008
parent "Nick Sabalausky" <a a.a> writes:
"Robert Fraser" <fraserofthenight gmail.com> wrote in message 
news:g55p65$1pga$1 digitalmars.com...

 Nick Sabalausky Wrote:


 "Ary Borenszweig" <ary esperanto.org.ar> wrote in message
 news:g54po3$2s7h$1 digitalmars.com...

 Bruce Adams a écrit :

 On Thu, 10 Jul 2008 02:44:07 +0100, Ary Borenszweig
 <ary esperanto.org.ar> wrote:


 Bruce Adams a écrit :

  Hi all,
        Alas this is not an announcement. It should be relatively 
 easy
 to knock up a few noddy scripts that can detect some kinds
 of potential problem.


 It should be relatively easy to write a plugin for Descent to do 
 that.
 Something similar to FindBugs for Java (
 http://findbugs.sourceforge.net/ ). Given a source file, you can ask
 Descent for it's AST with complete type resolution. You can apply the
 visitor pattern, which is supported by the AST nodes. You can store 
 in a
 list which variables are declared, and then if they are used in a
 function or are written too, you eliminate them. The remaining 
 entries
 in the list are the unused variables. It's a little harder for
 class/struct members, but it's still relatively easy.

 It is both helpful for a developer and for Descent, because the code
 that support that is kind of finished, but it isn't tested much (it's
 only used in highlighting code, which seems to work fine). Of course 
 I
 could do that, but atm I'm adding support for D2, plus it would be
 interesting if anyone else could join the project.


 This is a pet hate of mine. Tool should not be plug-ins for IDEs.


 The thing is, you write all the code, then, from time to time you run 
 that
 lint tool. You get 200 warnings. Will you want to correct them? Come 
 on,
 those are just warnings, and 200 of them! Maybe there's no time, maybe 
 it
 doesn't worth the effort. And you'd have to open up the code, remember
 what it was about, understanding it...


 Problem goes away with a thing called discipline. It's been about 10 
 years
 since I've allowed my warning counts to get anywhere near that big, and 
 even
 if it did suddenly happen to me today, there's not a chance I'd allow 
 myself
 to be intimidated by it.


 In an IDE: you finish writing a method. Even while writing at it, you 
 get
 the warnings. It's easy to correct, you are there, staring at the code. 
 It
 won't take your time, you have the code in your head, you know why the
 warning is there and how to remove it. And you do it.


 I agree a tool like this should be integrated/integratable into an IDE. 
 BUT,
 there should at least be a command-line version so that you aren't 
 married
 to a specific IDE (or any IDE at all if you happen to be that kind of
 person). I think the eclipse plugin that was proposed sounds great *as a
 start* because, from the sound of it (I wouldn't know, I don't like to 
 use
 Eclipse) it would allow *something* to be out there much more quickly 
 than
 starting a new command-line tool and getting it up to speed. Maybe it 
 could
 even be used for prototyping diagnostic ideas. BUT, I would consider a
 command-line version (even if it were built into the compiler - though 
 I'm
 sure that won't ever happen) to be essential, and something to eventually
 replace (or at least exist side-by-side) the interim Eclipse-based 
 solution.


 Just my thought...




 What Ary was saying is that an IDE tool can do the checks while you type.
 A command-line tool can't do that. And wrapping a GUI around a different
 process is a non-trivial task.

 Both tool types have their uses in different situations.


Good point. In which case, I still say a command-line version is essential, 
but it could happily co-exist with a more integrated IDE version (and maybe 
use a common library).
Jul 10 2008
prev sibling parent reply Bruno Medeiros <brunodomedeiros+spam com.gmail> writes:
Ary Borenszweig wrote:

 Bruce Adams a écrit :

 On Thu, 10 Jul 2008 02:44:07 +0100, Ary Borenszweig 
 <ary esperanto.org.ar> wrote:


 Bruce Adams a écrit :

  Hi all,
        Alas this is not an announcement. It should be relatively 
 easy to knock up a few noddy scripts that can detect some kinds
 of potential problem.


 It should be relatively easy to write a plugin for Descent to do 
 that. Something similar to FindBugs for Java ( 
 http://findbugs.sourceforge.net/ ). Given a source file, you can ask 
 Descent for it's AST with complete type resolution. You can apply the 
 visitor pattern, which is supported by the AST nodes. You can store 
 in a list which variables are declared, and then if they are used in 
 a function or are written too, you eliminate them. The remaining 
 entries in the list are the unused variables. It's a little harder 
 for class/struct members, but it's still relatively easy.

 It is both helpful for a developer and for Descent, because the code 
 that support that is kind of finished, but it isn't tested much (it's 
 only used in highlighting code, which seems to work fine). Of course 
 I could do that, but atm I'm adding support for D2, plus it would be 
 interesting if anyone else could join the project.


 This is a pet hate of mine. Tool should not be plug-ins for IDEs.


 
 The thing is, you write all the code, then, from time to time you run 
 that lint tool. You get 200 warnings. Will you want to correct them? 
 Come on, those are just warnings, and 200 of them! Maybe there's no 
 time, maybe it doesn't worth the effort. And you'd have to open up the 
 code, remember what it was about, understanding it...
 
 In an IDE: you finish writing a method. Even while writing at it, you 
 get the warnings. It's easy to correct, you are there, staring at the 
 code. It won't take your time, you have the code in your head, you know 
 why the warning is there and how to remove it. And you do it.
 
 Just my thought...


Ah, c'mon Ary, there is a reason why Eclipse IDE code is divided into 
.core and .ui plugins ;).

Yes, it is much better to see warnings while you are writing in the 
editor, instead of watching them all at once from the console.
But that doesn't invalidate the usefulness of being able to run some 
code analysis functionality from the command-line. One example is 
continuous integration, where one would like to automatically generate 
warnings for committed code, and them process that in some kind of 
report. It not one of those super-cool functionalities, but I do see 
some usefulness.



-- 
Bruno Medeiros - Software Developer, MSc. in CS/E graduate
http://www.prowiki.org/wiki4d/wiki.cgi?BrunoMedeiros#D
Jul 27 2008
parent reply "Kingsley" <kingsley.hendrickse gmail.com> writes:
Hi

has anyone made any progress with a lint for D? perhaps we could 
adapt this one https://github.com/facebook/flint

I could do with one for my intellij plugin.

--K
Jan 03 2015
parent "Brian Schott" <briancschott gmail.com> writes:
On Saturday, 3 January 2015 at 19:44:52 UTC, Kingsley wrote:

 Hi

 has anyone made any progress with a lint for D? perhaps we 
 could adapt this one https://github.com/facebook/flint

 I could do with one for my intellij plugin.

 --K


https://github.com/Hackerpilot/Dscanner#style-check
Jan 03 2015
prev sibling next sibling parent reply Markus Koskimies <markus reaaliaika.net> writes:
On Thu, 10 Jul 2008 01:42:17 +0100, Bruce Adams wrote:


 Hi all,
 Alas this is not an announcement. It should be relatively easy
 to
 knock up a few noddy scripts that can detect some kinds of potential
 problem. I occasionally find myself doing this for coding standard
 related things. The unused variable warning thing would seem to be a
 good start. How about writing a lint tool that starts with that as its
 only requirement and going forward from there?


[...]

 Any thoughts?


I have followed a little bit about conversation of D compiler warnings 
and such, and I know that there are people who think that these kinds of 
things should go to another tool.

I must disagree with this. Just like D has integrated doc generator, I 
would like to see it bundled with a tool doing all kinds of static checks 
also; it need not to be integral inside, but released with compiler and 
automatically invoked by the compiler. The reason for this hope is very 
simple - it would make things simple from developers point of view. Just 
write:

	dmd <all my D files>

...And it would not only compile the executable (possible recognizing 
which files need to be recompiled, normally done by make), but also run 
static checker. That's also the reason why I like the "-od" -style 
options (telling directories to put things).

I know that the UNIX way of thinking is to put everything in to separate 
programs, but that was just my thought.
Jul 09 2008
next sibling parent reply Bill Baxter <dnewsgroup billbaxter.com> writes:
Markus Koskimies wrote:

 On Thu, 10 Jul 2008 01:42:17 +0100, Bruce Adams wrote:



 
 I must disagree with this. Just like D has integrated doc generator, I 
 would like to see it bundled with a tool doing all kinds of static checks 
 also; it need not to be integral inside, but released with compiler and 
 automatically invoked by the compiler. The reason for this hope is very 
 simple - it would make things simple from developers point of view. Just 
 write:
 
 	dmd <all my D files>
 
 ...And it would not only compile the executable (possible recognizing 
 which files need to be recompiled, normally done by make), but also run 
 static checker. That's also the reason why I like the "-od" -style 
 options (telling directories to put things).


If the hypothetical lint tool existed, you could just write a script 
containing:

   <split up options>
   dmd $options_meant_for_dmd
   dlint $options_meant_for_dlint

There's just a bit of work to do there to filter out the options and 
split them into separate variables.  But if someone can write a lint 
tool, they should be able to figure out how to do that.  :-)

--bb
Jul 09 2008
parent reply Markus Koskimies <markus reaaliaika.net> writes:
On Thu, 10 Jul 2008 15:37:16 +0900, Bill Baxter wrote:


 Markus Koskimies wrote:

 On Thu, 10 Jul 2008 01:42:17 +0100, Bruce Adams wrote:


 
 

 I must disagree with this. Just like D has integrated doc generator, I
 would like to see it bundled with a tool doing all kinds of static
 checks also; it need not to be integral inside, but released with
 compiler and automatically invoked by the compiler. The reason for this
 hope is very simple - it would make things simple from developers point
 of view. Just write:
 
 	dmd <all my D files>
 
 ...And it would not only compile the executable (possible recognizing
 which files need to be recompiled, normally done by make), but also run
 static checker. That's also the reason why I like the "-od" -style
 options (telling directories to put things).


 
 If the hypothetical lint tool existed, you could just write a script
 containing:
 
    <split up options>
    dmd $options_meant_for_dmd
    dlint $options_meant_for_dlint
 
 There's just a bit of work to do there to filter out the options and
 split them into separate variables.  But if someone can write a lint
 tool, they should be able to figure out how to do that.  :-)


In ideal world that's true. But in practice (my experience with C++ & 
lint) if the lint-like tool is not a part of the compiler release, you 
spend a lots of time to configure the lint to understand the compiler 
options and features.

But that's just my opinion. I would prefer a compiler release, where:

	dmd -w <all the files & options>
or:
	gdc -w <all the options & files>

...is alias for:

	dlint <all the files & options> \
	&& \
	dmd/gdc <all the files & options>

It really does not matter if the lint-like tool is integral part of the 
compiler, but it would help a lot if the compiler could be instructed 
first to make static analysis before starting to generate code. Sure it 
would be great, if the lint and compiler understand the same language 
(i.e. they share the same parser) and same options.

It is just the way I normally work; I enable all possible warnings and I 
would like to get rid of them all.
Jul 10 2008
next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
I think that having a separate lint, a separate code commenting tool, and a
separate unittest controller, may be better, because putting such things into
the compiler makes the development of the compiler slower (because I think it's
better for Walter to focus on just the compiler, reducing and focusing his
work), and such tools become slower.
On the other hand standard tools may be unfit for D or they be difficult to use
(so they may not scale *down*. ddoc and D unittests scale down very well, I
mean you can use them even if you write a 15-lines program and you have read
nearly nothing about how to use them).
So I suggest to develop standard tools present in all D distributions, really
easy and fast to use, with hooks from the compiler (so their syntax is good!)
able to scale down, and developed/debugged by the community too. The purpose of
such tools is to have something that can be used almost with no manual, fast,
and reliable, and needing nearly nothing else.
For people that have to document a 10000+ lines program then they can use
doxigen or one very powerful lint tool, developed by other people.
This is how Python works: built-in the std lib you find very easy to use tools
for most purposes. But you often use external more powerful and less easy to
use tools when you need something more refined.

Bye,
bearophile
Jul 10 2008
parent Markus Koskimies <markus reaaliaika.net> writes:
On Thu, 10 Jul 2008 04:56:15 -0400, bearophile wrote:


 I think that having a separate lint, a separate code commenting tool,
 and a separate unittest controller, may be better, because putting such
 things into the compiler makes the development of the compiler slower
 (because I think it's better for Walter to focus on just the compiler,
 reducing and focusing his work), and such tools become slower.


I partly agree; yes, the basic tool gives you basic features (like code 
commenting and unit testing), and when you run out of their capabilities, 
it is good to have more powerful alternatives available. It is of course 
not an option that one guy does it all; and I think that no one is 
suggesting that?

Just like you said, the D basic set scales down extremely well, and one 
of the reasons I really like D is that it is also suitable for making 
small programs fast. It's pretty much like a compiled Python :D

What about scaling up? In software development (both work & home), I 
could think about following things:

- Building; D compiler makes it easy to build the software from multiple 
files, but when the project grows, at some point there is probably need 
for makefiles and building scripts. That's why it's necessary that D 
compiler has command line interface, and ability just compile, not link.

- Testing; The larger and more complex is the project, the larger and 
more complex comes the testing. The language spec & coding practices can 
make this either easier or more difficult; the easier it is to extract 
piece of code to a test bench, the easier it is to set up test 
environment.

- Version control; Again, since D can compile projects from multiple 
files, it is enough for small projects and few people. But if the number 
of files and people grow, you start to think about svn.

- Documentation; Yes, Ddoc goes well, and at some point you may start to 
think doxygen.

- Refactoring; D is very similar to Python, that it goes far before 
people are starting to look for refactoring tools. I'm not sure if there 
are any viable alternatives except for Java. From the language point of 
view, I think that D has better abilities for large projects than java. 
Refactoring is of course not the job performed by compiler (I think that 
the compiler should never modify source code).

What I try to say, is that there are IMO two things; (1) the default 
tools provided by the compiler/linker release, and (2) the abilities to 
bind the compiler/linker to external tools.


 So I suggest to
 develop standard tools present in all D distributions, really easy and
 fast to use, with hooks from the compiler (so their syntax is good!)
 able to scale down, and developed/debugged by the community too.


Agreed.


 This
 is how Python works: built-in the std lib you find very easy to use
 tools for most purposes. But you often use external more powerful and
 less easy to use tools when you need something more refined.


Ah, Python is one of my favorite languages and partly just because of its 
built-in standard library :D
Jul 10 2008
prev sibling parent reply Yigal Chripun <yigal100 gmail.com> writes:
Markus Koskimies wrote:

 On Thu, 10 Jul 2008 15:37:16 +0900, Bill Baxter wrote:
 

 Markus Koskimies wrote:

 On Thu, 10 Jul 2008 01:42:17 +0100, Bruce Adams wrote:



 I must disagree with this. Just like D has integrated doc generator, I
 would like to see it bundled with a tool doing all kinds of static
 checks also; it need not to be integral inside, but released with
 compiler and automatically invoked by the compiler. The reason for this
 hope is very simple - it would make things simple from developers point
 of view. Just write:

 	dmd <all my D files>

 ...And it would not only compile the executable (possible recognizing
 which files need to be recompiled, normally done by make), but also run
 static checker. That's also the reason why I like the "-od" -style
 options (telling directories to put things).


 If the hypothetical lint tool existed, you could just write a script
 containing:

    <split up options>
    dmd $options_meant_for_dmd
    dlint $options_meant_for_dlint

 There's just a bit of work to do there to filter out the options and
 split them into separate variables.  But if someone can write a lint
 tool, they should be able to figure out how to do that.  :-)


 
 In ideal world that's true. But in practice (my experience with C++ & 
 lint) if the lint-like tool is not a part of the compiler release, you 
 spend a lots of time to configure the lint to understand the compiler 
 options and features.
 
 But that's just my opinion. I would prefer a compiler release, where:
 
 	dmd -w <all the files & options>
 or:
 	gdc -w <all the options & files>
 
 ....is alias for:
 
 	dlint <all the files & options> \
 	&& \
 	dmd/gdc <all the files & options>
 
 It really does not matter if the lint-like tool is integral part of the 
 compiler, but it would help a lot if the compiler could be instructed 
 first to make static analysis before starting to generate code. Sure it 
 would be great, if the lint and compiler understand the same language 
 (i.e. they share the same parser) and same options.
 
 It is just the way I normally work; I enable all possible warnings and I 
 would like to get rid of them all.


IMO, the UNIX way is the correct way. I actually prefer to remove the
documentation generation from DMD.
the compiler should only compile code and nothing else.
if you want to do something more complex than just compile a file you
should use a build tool. a build tool is where you want to integrate all
the separate tools together. look at ant for example: you can define an
ant task for compilation, a different task for doc generation, another
to run lint tools, etc... ant itself uses xml files (which is bad IMO)
to define those and is extensible (which is good).
there are build tools that are written as libs in a scripting language
and your "makefile" than just become a regular python script (scons) or
ruby script (rake/rant).
also, build tools like that can be integrated in your IDE. (If i'm not
mistaken eclipse can work with ant projects, so you can use gui for
everything)

just use ant/rake/scons/what ever instead of dmd in your example.
All of those are orders of magnitude better than make and even with that
 you can have:
$> make all
to statically check your files, compile and link them, generate docs and
 order from pizza hut all in one go.
Jul 11 2008
parent reply "Nick Sabalausky" <a a.a> writes:
"Yigal Chripun" <yigal100 gmail.com> wrote in message 
news:g57vk8$tma$1 digitalmars.com...

 Markus Koskimies wrote:

 On Thu, 10 Jul 2008 15:37:16 +0900, Bill Baxter wrote:


 Markus Koskimies wrote:

 On Thu, 10 Jul 2008 01:42:17 +0100, Bruce Adams wrote:



 I must disagree with this. Just like D has integrated doc generator, I
 would like to see it bundled with a tool doing all kinds of static
 checks also; it need not to be integral inside, but released with
 compiler and automatically invoked by the compiler. The reason for this
 hope is very simple - it would make things simple from developers point
 of view. Just write:

 dmd <all my D files>

 ...And it would not only compile the executable (possible recognizing
 which files need to be recompiled, normally done by make), but also run
 static checker. That's also the reason why I like the "-od" -style
 options (telling directories to put things).


 If the hypothetical lint tool existed, you could just write a script
 containing:

    <split up options>
    dmd $options_meant_for_dmd
    dlint $options_meant_for_dlint

 There's just a bit of work to do there to filter out the options and
 split them into separate variables.  But if someone can write a lint
 tool, they should be able to figure out how to do that.  :-)


 In ideal world that's true. But in practice (my experience with C++ &
 lint) if the lint-like tool is not a part of the compiler release, you
 spend a lots of time to configure the lint to understand the compiler
 options and features.

 But that's just my opinion. I would prefer a compiler release, where:

 dmd -w <all the files & options>
 or:
 gdc -w <all the options & files>

 ....is alias for:

 dlint <all the files & options> \
 && \
 dmd/gdc <all the files & options>

 It really does not matter if the lint-like tool is integral part of the
 compiler, but it would help a lot if the compiler could be instructed
 first to make static analysis before starting to generate code. Sure it
 would be great, if the lint and compiler understand the same language
 (i.e. they share the same parser) and same options.

 It is just the way I normally work; I enable all possible warnings and I
 would like to get rid of them all.


 IMO, the UNIX way is the correct way. I actually prefer to remove the
 documentation generation from DMD.
 the compiler should only compile code and nothing else.
 if you want to do something more complex than just compile a file you
 should use a build tool. a build tool is where you want to integrate all
 the separate tools together. look at ant for example: you can define an
 ant task for compilation, a different task for doc generation, another
 to run lint tools, etc... ant itself uses xml files (which is bad IMO)
 to define those and is extensible (which is good).
 there are build tools that are written as libs in a scripting language
 and your "makefile" than just become a regular python script (scons) or
 ruby script (rake/rant).
 also, build tools like that can be integrated in your IDE. (If i'm not
 mistaken eclipse can work with ant projects, so you can use gui for
 everything)

 just use ant/rake/scons/what ever instead of dmd in your example.
 All of those are orders of magnitude better than make and even with that
 you can have:
 $> make all
 to statically check your files, compile and link them, generate docs and
 order from pizza hut all in one go.


How can having extra *optional* functionality in a tool possibly cause any 
actual *practical* problems (ie, other than the highly abstract notion of 
purity)? I can't think of a single realisic scenario where the difference in 
the following two snippets would actualy make a real difference:

makecoffee  ...args...
jumpupanddown ...args...

vs:

multitool -makecoffee ...args...
multitool -jumpupanddown ...args...

I can understand that keeping separate tasks in separate tools can be 
considered nice and clean and give me a warm fuzzy feeling. But, what real 
concrete difference could it possibly make?
Jul 11 2008
next sibling parent "Bruce Adams" <tortoise_74 yeah.who.co.uk> writes:
On Fri, 11 Jul 2008 18:43:08 +0100, Nick Sabalausky <a a.a> wrote:


 How can having extra *optional* functionality in a tool possibly cause  
 any
 actual *practical* problems (ie, other than the highly abstract notion of
 purity)? I can't think of a single realisic scenario where the  
 difference in
 the following two snippets would actualy make a real difference:

 makecoffee  ...args...
 jumpupanddown ...args...

 vs:

 multitool -makecoffee ...args...
 multitool -jumpupanddown ...args...

 I can understand that keeping separate tasks in separate tools can be
 considered nice and clean and give me a warm fuzzy feeling. But, what  
 real
 concrete difference could it possibly make?


Its more a philosphical point. If you are given something for free you
are more likely to use it and therefore be tied down by its limitations.
Though it might also be the hook you need to look further affield for  
something
better.
Another risk is dilluting the effort. More work spent on adding bells and  
whistles
is less spent on making the engine perform its job well.
A third risk is introducing bugs by violating the KISS principle (keep it  
simple stupid).

Still you can have the best of both worlds as has already been discussed  
by having
one program to instantiate them all and in the build process run them.
Jul 11 2008
prev sibling parent Yigal Chripun <yigal100 gmail.com> writes:
Nick Sabalausky wrote:

 "Yigal Chripun" <yigal100 gmail.com> wrote in message 
 news:g57vk8$tma$1 digitalmars.com...

 Markus Koskimies wrote:

 On Thu, 10 Jul 2008 15:37:16 +0900, Bill Baxter wrote:


 Markus Koskimies wrote:

 On Thu, 10 Jul 2008 01:42:17 +0100, Bruce Adams wrote:
 I must disagree with this. Just like D has integrated doc generator, I
 would like to see it bundled with a tool doing all kinds of static
 checks also; it need not to be integral inside, but released with
 compiler and automatically invoked by the compiler. The reason for this
 hope is very simple - it would make things simple from developers point
 of view. Just write:

 dmd <all my D files>

 ...And it would not only compile the executable (possible recognizing
 which files need to be recompiled, normally done by make), but also run
 static checker. That's also the reason why I like the "-od" -style
 options (telling directories to put things).


 If the hypothetical lint tool existed, you could just write a script
 containing:

    <split up options>
    dmd $options_meant_for_dmd
    dlint $options_meant_for_dlint

 There's just a bit of work to do there to filter out the options and
 split them into separate variables.  But if someone can write a lint
 tool, they should be able to figure out how to do that.  :-)


 In ideal world that's true. But in practice (my experience with C++ &
 lint) if the lint-like tool is not a part of the compiler release, you
 spend a lots of time to configure the lint to understand the compiler
 options and features.

 But that's just my opinion. I would prefer a compiler release, where:

 dmd -w <all the files & options>
 or:
 gdc -w <all the options & files>

 ....is alias for:

 dlint <all the files & options> \
 && \
 dmd/gdc <all the files & options>

 It really does not matter if the lint-like tool is integral part of the
 compiler, but it would help a lot if the compiler could be instructed
 first to make static analysis before starting to generate code. Sure it
 would be great, if the lint and compiler understand the same language
 (i.e. they share the same parser) and same options.

 It is just the way I normally work; I enable all possible warnings and I
 would like to get rid of them all.


 IMO, the UNIX way is the correct way. I actually prefer to remove the
 documentation generation from DMD.
 the compiler should only compile code and nothing else.
 if you want to do something more complex than just compile a file you
 should use a build tool. a build tool is where you want to integrate all
 the separate tools together. look at ant for example: you can define an
 ant task for compilation, a different task for doc generation, another
 to run lint tools, etc... ant itself uses xml files (which is bad IMO)
 to define those and is extensible (which is good).
 there are build tools that are written as libs in a scripting language
 and your "makefile" than just become a regular python script (scons) or
 ruby script (rake/rant).
 also, build tools like that can be integrated in your IDE. (If i'm not
 mistaken eclipse can work with ant projects, so you can use gui for
 everything)

 just use ant/rake/scons/what ever instead of dmd in your example.
 All of those are orders of magnitude better than make and even with that
 you can have:
 $> make all
 to statically check your files, compile and link them, generate docs and
 order from pizza hut all in one go.


 
 How can having extra *optional* functionality in a tool possibly cause any 
 actual *practical* problems (ie, other than the highly abstract notion of 
 purity)? I can't think of a single realisic scenario where the difference in 
 the following two snippets would actualy make a real difference:
 
 makecoffee  ...args...
 jumpupanddown ...args...
 
 vs:
 
 multitool -makecoffee ...args...
 multitool -jumpupanddown ...args...
 
 I can understand that keeping separate tasks in separate tools can be 
 considered nice and clean and give me a warm fuzzy feeling. But, what real 
 concrete difference could it possibly make? 
 
 


here's a scenario for you:
ddoc and dmd - ddoc reads the ast that the compiler front-end generates
and changes it by mistake, thus affecting code generation. bundling both
in the same executable created an integration bug where docs generation
affected the executable.
this is just a hypothetical bug, of course, but one that could
eventually happen.
if ddoc was in a separate executable (sharing a common library with a
compiler cli interface) than such bug cannot happen. since you put the
compiler front-end in the lib above, you do not need to implement it
twice. but you do get two separate executables which cannot affect each
other.

also, you can link that same lib and reuse in other tools as well -
editors, IDEs, lint tools, docs generators, build tools, etc..
no need to make one huge executable of them all combined.

IMO, the compiler should be a shared lib used by different executables
to perform different tasks.
Jul 12 2008
prev sibling parent reply "Bruce Adams" <tortoise_74 yeah.who.co.uk> writes:
On Thu, 10 Jul 2008 06:28:59 +0100, Markus Koskimies  
<markus reaaliaika.net> wrote:


 I have followed a little bit about conversation of D compiler warnings
 and such, and I know that there are people who think that these kinds of
 things should go to another tool.

 I must disagree with this. Just like D has integrated doc generator, I
 would like to see it bundled with a tool doing all kinds of static checks
 also; it need not to be integral inside, but released with compiler and
 automatically invoked by the compiler. The reason for this hope is very
 simple - it would make things simple from developers point of view. Just
 write:

 	dmd <all my D files>

 ...And it would not only compile the executable (possible recognizing
 which files need to be recompiled, normally done by make), but also run
 static checker. That's also the reason why I like the "-od" -style
 options (telling directories to put things).


I am in the camp that would have more warnings in dmd too but I can't see  
that
happening. gcc is an example of both the good and bad of this. It has  
10,000
options making it non trivial to understand the API let alone test it.
The options have to reworked for each
target OS by configure command otherwise treat warnings as errors makes  
code
fail to compile. The warnings changing with each version of gcc is a bit  
like
minor language specification changes (as Walter noted).

With all the warnings switched on your need for a lint is vastly reduced.
I a have so far unable to convince my workplace of the need for lint  
because
we use gcc and it has a lot of warnings. I believe the gain from lint is  
still
significant but its harder to demonstrate.

 From what I hear about ddoc it is vastly inferior to Doxygen (speaking as  
usual from ignorance).
Doxygen is a dedicated documentation tool so its good at that one thing.
For dmd the compilation side is most important and ddoc is probably not  
even third fiddle.
Doxygen also has the benefit of being language independent.
You have to actively choose to use it though.
There is a lot of benefit to be had from the community making  
recommendations for
preferred tools rather than proliferating. In the case of thing you  
integrate into your
build process at least. This is not true for IDEs (which are more  
subjective anyway).


 I know that the UNIX way of thinking is to put everything in to separate
 programs, but that was just my thought.


It is and it isn't. Anyway you can still have one program as the driver
that invokes multiple programs. gcc does this under the bonnet.

Regards,

Bruce.
Jul 10 2008
next sibling parent Markus Koskimies <markus reaaliaika.net> writes:
On Thu, 10 Jul 2008 09:26:19 +0100, Bruce Adams wrote:


 I am in the camp that would have more warnings in dmd too but I can't
 see that happening.


That's a little bit sad. IMO there are two different things in the 
compiler; (1) if it can or cannot generate code, i.e. if the source 
follows language spec or not (giving error, if it cannot), and (2) being 
able to generate code, but it thinks it may not be what it was meant to 
be (giving warning).

But I'm patient and I can live with most of the D compiler/language 
design decisions :) There is just not currently any better alternatives 
for those purposes I use D. In my work, I of course use the language the 
employer says (that is, C, C++ and assemblers), and at my freetime I 
regularly use Python, Java and D (each for different purposes).


 gcc is an example of both the good and bad of this. It has
 10,000
 options making it non trivial to understand the API let alone test it.
 The options have to reworked for each target OS by configure command
 otherwise treat warnings as errors makes code
 fail to compile. The warnings changing with each version of gcc is a bit
 like
 minor language specification changes (as Walter noted).


So true :D


 With all the warnings switched on your need for a lint is vastly
 reduced. 


Absolutely true. That's why I generally like to use gcc/g++. I have 
experience of setting up & maintaining lint for an embedded C compiler, 
and that was quite horrible. That's why I like that the compiler has the 
basic checkings built in.


 I believe the gain from lint is still
 significant but its harder to demonstrate.


I'm not sure about that, of course it's very much up to the effort for 
configuring lint for the project and maintaining it. But yes, sure, 
probably generic Win/Linux projects are much easier than a specialized C 
compiler with bunch of hardware related extensions and non-standard 
"standard" library & OS.

[Ddoc/doxygen]

 In the case of thing you integrate into your
 build process at least. This is not true for IDEs (which are more
 subjective anyway).


I'm not using IDE not in my work and neither at home. That's why I 
implicitly assume that a tool is integrated to a build process, not to an 
IDE.


 I know that the UNIX way of thinking is to put everything in to
 separate programs, but that was just my thought.


 
 It is and it isn't. Anyway you can still have one program as the driver
 that invokes multiple programs. gcc does this under the bonnet.


Yes it does and even though the gcc can be criticized to be complex, it's 
IMO still good to have HLL compiler(s), assembler / machine code 
generator and linker in the same package.
Jul 10 2008
prev sibling parent reply Walter Bright <newshound1 digitalmars.com> writes:
Bruce Adams wrote:

  From what I hear about ddoc it is vastly inferior to Doxygen (speaking 
 as usual from ignorance).


Ddoc's purpose is to:

1. set a minimum standard for documentation
2. allow documentation to be written in a typical comment style

At that, it has succeeded spectacularly. Prior to Ddoc, for example, the 
Phobos documentation stunk.

My issue with Doxygen is that:

1. it won't get used consistently (being a third party tool) and so no 
minimum standard
2. the documentation comments look like another programming language
Jul 10 2008
next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"Walter Bright" <newshound1 digitalmars.com> wrote in message 
news:g55rle$1uoh$1 digitalmars.com...

 Bruce Adams wrote:

  From what I hear about ddoc it is vastly inferior to Doxygen (speaking 
 as usual from ignorance).


 Ddoc's purpose is to:

 1. set a minimum standard for documentation
 2. allow documentation to be written in a typical comment style

 At that, it has succeeded spectacularly. Prior to Ddoc, for example, the 
 Phobos documentation stunk.

 My issue with Doxygen is that:

 1. it won't get used consistently (being a third party tool) and so no 
 minimum standard
 2. the documentation comments look like another programming language


I'm not very familiar with Doxygen, but from the sound of it, it reminds me 

it's garbage compared to Ddoc. With Ddoc, I can actually read my own 

know, but to me I can't imagine it being worth giving up the ability to use 
a very natural and unobtrusive style when writing my documentation-comments.
Jul 10 2008
next sibling parent reply Bill Baxter <dnewsgroup billbaxter.com> writes:
Nick Sabalausky wrote:

 "Walter Bright" <newshound1 digitalmars.com> wrote in message 
 news:g55rle$1uoh$1 digitalmars.com...

 Bruce Adams wrote:

  From what I hear about ddoc it is vastly inferior to Doxygen (speaking 
 as usual from ignorance).


 Ddoc's purpose is to:

 1. set a minimum standard for documentation
 2. allow documentation to be written in a typical comment style

 At that, it has succeeded spectacularly. Prior to Ddoc, for example, the 
 Phobos documentation stunk.

 My issue with Doxygen is that:

 1. it won't get used consistently (being a third party tool) and so no 
 minimum standard
 2. the documentation comments look like another programming language


 
 I'm not very familiar with Doxygen, but from the sound of it, it reminds me 

 it's garbage compared to Ddoc. With Ddoc, I can actually read my own 

 know, but to me I can't imagine it being worth giving up the ability to use 
 a very natural and unobtrusive style when writing my documentation-comments.


Doxygen only looks like another programming language if you try to use 
every single feature it provides.  If you stick with the basic the set 
of features (basically, the things that DDoc provides) it looks pretty 
much like DDoc.  My main gripe with DDoc is that those 
$MAKE_THIS_BOLD(macros) everywhere look ugly.  Much uglier than 
Doxygen's keywords like  param, IMHO.

NaturalDocs is nice (http://www.naturaldocs.org/).  It really does a 
much better job of delivering on point 2. above than DDoc does (i.e. 
using typical comment style).  Unfortunately it hasn't really caught on. 
  Here are the examples: http://www.naturaldocs.org/documenting.html.

But I think CandyDoc for DDoc gives the nicest output of all the options 
I've seen.

--bb
Jul 10 2008
next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"Bill Baxter" <dnewsgroup billbaxter.com> wrote in message 
news:g56avu$56h$1 digitalmars.com...

 Nick Sabalausky wrote:

 "Walter Bright" <newshound1 digitalmars.com> wrote in message 
 news:g55rle$1uoh$1 digitalmars.com...

 Bruce Adams wrote:

  From what I hear about ddoc it is vastly inferior to Doxygen (speaking 
 as usual from ignorance).


 Ddoc's purpose is to:

 1. set a minimum standard for documentation
 2. allow documentation to be written in a typical comment style

 At that, it has succeeded spectacularly. Prior to Ddoc, for example, the 
 Phobos documentation stunk.

 My issue with Doxygen is that:

 1. it won't get used consistently (being a third party tool) and so no 
 minimum standard
 2. the documentation comments look like another programming language


 I'm not very familiar with Doxygen, but from the sound of it, it reminds 

 but it's garbage compared to Ddoc. With Ddoc, I can actually read my own 

 know, but to me I can't imagine it being worth giving up the ability to 
 use a very natural and unobtrusive style when writing my 
 documentation-comments.


 Doxygen only looks like another programming language if you try to use 
 every single feature it provides.  If you stick with the basic the set of 
 features (basically, the things that DDoc provides) it looks pretty much 
 like DDoc.  My main gripe with DDoc is that those $MAKE_THIS_BOLD(macros) 
 everywhere look ugly.  Much uglier than Doxygen's keywords like  param, 
 IMHO.


True. I have noticed that.


 NaturalDocs is nice (http://www.naturaldocs.org/).  It really does a much 
 better job of delivering on point 2. above than DDoc does (i.e. using 
 typical comment style).  Unfortunately it hasn't really caught on. Here 
 are the examples: http://www.naturaldocs.org/documenting.html.


Very nice. I think I've come across that once before, actually, and then 
promptly forgot about it. But the idea that automatic documentation syntax 
could be made so natural-looking while still performing the job, all with 
such simple parsing rules... Well, that really stuck with me and I was never 



 But I think CandyDoc for DDoc gives the nicest output of all the options 
 I've seen.

 --bb
Jul 10 2008
parent reply bearophile <bearophileHUGS lycos.com> writes:
Nick Sabalausky or Bill Baxter:

 NaturalDocs is nice (http://www.naturaldocs.org/).  It really does a much 
 better job of delivering on point 2. above than DDoc does (i.e. using 
 typical comment style).  Unfortunately it hasn't really caught on. Here 
 are the examples: http://www.naturaldocs.org/documenting.html.




This is one of the first examples:

/*
   Function: Multiply

   Multiplies two integers.

   Parameters:

      x - The first integer.
      y - The second integer.

   Returns:

      The two integers multiplied together.

   See Also:

      <Divide>
*/
int Multiply (int x, int y)
   {  return x * y;  };

It's nice, but it uses too much vertical space, so the eye loses itself in all
that space, and the programs become too much long. To improve readability you
should  reduce used space.

The first line: "Function: Multiply" seems redundant (and it's a bad thing)
because the true function name and the comments can grow to differ.

Anyway, I don't know if NaturalDocs creators allow D developers to bundle this
NaturalDocs into *every* D distribution present and future.

Bye,
bearophile
Jul 11 2008
parent reply Bill Baxter <dnewsgroup billbaxter.com> writes:
bearophile wrote:

 Nick Sabalausky or Bill Baxter:

 NaturalDocs is nice (http://www.naturaldocs.org/).  It really does a much 
 better job of delivering on point 2. above than DDoc does (i.e. using 
 typical comment style).  Unfortunately it hasn't really caught on. Here 
 are the examples: http://www.naturaldocs.org/documenting.html.




 
 This is one of the first examples:
 
 /*
    Function: Multiply
 
    Multiplies two integers.
 
    Parameters:
 
       x - The first integer.
       y - The second integer.
 
    Returns:
 
       The two integers multiplied together.
 
    See Also:
 
       <Divide>
 */
 int Multiply (int x, int y)
    {  return x * y;  };
 
 It's nice, but it uses too much vertical space, so the eye loses itself in all
that space, and the programs become too much long. To improve readability you
should  reduce used space.
 
 The first line: "Function: Multiply" seems redundant (and it's a bad thing)
because the true function name and the comments can grow to differ.
 
 Anyway, I don't know if NaturalDocs creators allow D developers to bundle this
NaturalDocs into *every* D distribution present and future.


Actually I don't think Natural Docs really supports D at all.
I was just mentioning it for the overall markup style.

About the vertical space in that example: the space after the labels is 
not required by NaturalDocs.  So it could be a bit more compact.  Still 
it would be nice to be able to say "See Also: <Divide>" all on one line.

About the "Function: Multiply" redundancy, I think that's because the 
whole thing is done as a perl script and it's not quite up to the task 
of parsing C++ to figure out what the next grammatical entity is.

There's also reST (http://docutils.sourceforge.net/rst.html), which has 
been thought out very thoroughly, but the choices they've made for the 
most common markup tasks don't sit well with me.   (Like using :Section: 
for sections, and too many backticks everywhere.)

--bb
Jul 11 2008
next sibling parent "Bruce Adams" <tortoise_74 yeah.who.co.uk> writes:
On Fri, 11 Jul 2008 22:09:28 +0100, Bill Baxter  
<dnewsgroup billbaxter.com> wrote:

 About the vertical space in that example: the space after the labels is  
 not required by NaturalDocs.  So it could be a bit more compact.  Still  
 it would be nice to be able to say "See Also: <Divide>" all on one line.


If its just "key : value"  until end of comment or next instance of "^key:"
that could work too


 About the "Function: Multiply" redundancy, I think that's because the  
 whole thing is done as a perl script and it's not quite up to the task  
 of parsing C++ to figure out what the next grammatical entity is.


D however is parseable using an ordinary grammar so this should be less of  
an issue.

I think I'm sold on the idea already.
Jul 11 2008
prev sibling parent Walter Bright <newshound1 digitalmars.com> writes:
Bill Baxter wrote:

 About the "Function: Multiply" redundancy, I think that's because the 
 whole thing is done as a perl script and it's not quite up to the task 
 of parsing C++ to figure out what the next grammatical entity is.


An essential part of Ddoc is the ability to 'fill in the boilerplate' by 
using the semantic information from parsing the declaration.
Jul 21 2008
prev sibling parent Leandro Lucarella <llucax gmail.com> writes:
Bill Baxter, el 11 de julio a las 09:54 me escribiste:

I'm not very familiar with Doxygen, but from the sound of it, it reminds me of 

garbage compared to Ddoc. With Ddoc, I can actually read my own comments! Maybe 

imagine it being worth giving up the ability to use a very natural and 
unobtrusive style when writing my documentation-comments.


 
 Doxygen only looks like another programming language if you try to use every 
 single feature it provides.  If you stick with the basic the set of features 
 (basically, the things that DDoc provides) it looks pretty much like DDoc.  My 
 main gripe with DDoc is that those $MAKE_THIS_BOLD(macros) everywhere look
ugly.  
 Much uglier than Doxygen's keywords like  param, IMHO.
 
 NaturalDocs is nice (http://www.naturaldocs.org/).  It really does a much
better 
 job of delivering on point 2. above than DDoc does (i.e. using typical comment 
 style).  Unfortunately it hasn't really caught on.  Here are the examples: 
 http://www.naturaldocs.org/documenting.html.
 
 But I think CandyDoc for DDoc gives the nicest output of all the options I've 
 seen.


I really like RestructuredText[1], in combination with Sphinx[2] it make a
great tool to write documentation (reference and tutorial like).

Too bad is too Python-specific...

[1] http://docutils.sourceforge.net/rst.html
[2] http://sphinx.pocoo.org/

-- 
Leandro Lucarella (luca) | Blog colectivo: http://www.mazziblog.com.ar/blog/
----------------------------------------------------------------------------
GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145  104C 949E BFB6 5F5A 8D05)
----------------------------------------------------------------------------
More than 50% of the people in the world have never made
Or received a telephone call
Jul 11 2008
prev sibling parent reply JAnderson <ask me.com> writes:
Nick Sabalausky wrote:

 "Walter Bright" <newshound1 digitalmars.com> wrote in message 
 news:g55rle$1uoh$1 digitalmars.com...

 Bruce Adams wrote:

  From what I hear about ddoc it is vastly inferior to Doxygen (speaking 
 as usual from ignorance).


 Ddoc's purpose is to:

 1. set a minimum standard for documentation
 2. allow documentation to be written in a typical comment style

 At that, it has succeeded spectacularly. Prior to Ddoc, for example, the 
 Phobos documentation stunk.

 My issue with Doxygen is that:

 1. it won't get used consistently (being a third party tool) and so no 
 minimum standard
 2. the documentation comments look like another programming language


 
 I'm not very familiar with Doxygen, but from the sound of it, it reminds me 

 it's garbage compared to Ddoc. With Ddoc, I can actually read my own 

 know, but to me I can't imagine it being worth giving up the ability to use 
 a very natural and unobtrusive style when writing my documentation-comments.
 
 


Doxygen is a little complicated however it has a huge amount of 
flexibility.  There are some nice GUIs that work on top of Doxygen which 
make things easier.  You just tick a couple of boxes and it creates 
settging for you.  It even allows you to create fancy tree graphics of 
everything in the project.

-Joel
Jul 11 2008
parent "Nick Sabalausky" <a a.a> writes:
"JAnderson" <ask me.com> wrote in message 
news:g57ss9$n76$2 digitalmars.com...

 Nick Sabalausky wrote:

 "Walter Bright" <newshound1 digitalmars.com> wrote in message 
 news:g55rle$1uoh$1 digitalmars.com...

 Bruce Adams wrote:

  From what I hear about ddoc it is vastly inferior to Doxygen (speaking 
 as usual from ignorance).


 Ddoc's purpose is to:

 1. set a minimum standard for documentation
 2. allow documentation to be written in a typical comment style

 At that, it has succeeded spectacularly. Prior to Ddoc, for example, the 
 Phobos documentation stunk.

 My issue with Doxygen is that:

 1. it won't get used consistently (being a third party tool) and so no 
 minimum standard
 2. the documentation comments look like another programming language


 I'm not very familiar with Doxygen, but from the sound of it, it reminds 

 but it's garbage compared to Ddoc. With Ddoc, I can actually read my own 

 know, but to me I can't imagine it being worth giving up the ability to 
 use a very natural and unobtrusive style when writing my 
 documentation-comments.


 Doxygen is a little complicated however it has a huge amount of 
 flexibility.  There are some nice GUIs that work on top of Doxygen which 
 make things easier.  You just tick a couple of boxes and it creates 
 settging for you.  It even allows you to create fancy tree graphics of 
 everything in the project.


I don't see any reason why that couldn't also be done with something like 
Ddoc or NaturalDocs.
Jul 11 2008
prev sibling parent Markus Koskimies <markus reaaliaika.net> writes:
On Thu, 10 Jul 2008 13:32:47 -0700, Walter Bright wrote:


 Bruce Adams wrote:
 My issue with Doxygen is that:
 
 1. it won't get used consistently (being a third party tool) and so no
 minimum standard


I have used it for a completely foreign code to make it browsable. It 
performs well, but I still think it is not something that needs to be 
added to a compiler. Ddoc does the job just fine.


 2. the documentation comments look like another programming language


Depends hugely what you were instructed it to do. Regularly, the 
browsable code that dogygen does with minimum configuration is very good 
for getting used to a foreign code.
Jul 10 2008
prev sibling parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
https://github.com/Hackerpilot/Dscanner
Jan 03 2015
parent "Kingsley" <kingsley.hendrickse gmail.com> writes:
On Sunday, 4 January 2015 at 00:05:51 UTC, Martin Nowak wrote:

 https://github.com/Hackerpilot/Dscanner


Brilliant thanks - I've successfully integrated it into my 
IntelliJ plugin
Jan 05 2015