www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - ddox empty public methods/interfaces etc

reply Andrey <andrey kabylin.ru> writes:
Hello is there way to automatically generate documentation for 
public methods, interfaces, fields etc.? e.g. now I should write 
somethink like this to generate documentation for enum Bacgkround:

 ///
 enum Background {
     transparent,  ///
     light,  ///
     dark,  ///
     action,  /// Background for action panel, e.g. with buttons 
 OK, Cancel etc.
 }


I would like to write insted this:

 enum Background {
     transparent,
     light,
     dark,
     action,  /// Background for action panel, e.g. with buttons 
 OK, Cancel etc.
 }


and avoid all redundant comments.
Nov 06 2017
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 11/6/17 11:01 PM, Andrey wrote:

 Hello is there way to automatically generate documentation for public 
 methods, interfaces, fields etc.? e.g. now I should write somethink like 
 this to generate documentation for enum Bacgkround:

 ///
 enum Background {
     transparent,  ///
     light,  ///
     dark,  ///
     action,  /// Background for action panel, e.g. with buttons OK, 
 Cancel etc.
 }


 
 I would like to write insted this:

 enum Background {
     transparent,
     light,
     dark,
     action,  /// Background for action panel, e.g. with buttons OK, 
 Cancel etc.
 }


 
 and avoid all redundant comments.


Sorry, this isn't possible. Ddoc requires opt-in for public 
documentation. The alternative would be opt-out, which would look even 
worse I think.

-Steve
Nov 07 2017
parent reply Andrey <andrey kabylin.ru> writes:
On Tuesday, 7 November 2017 at 14:02:28 UTC, Steven Schveighoffer 
wrote:

 On 11/6/17 11:01 PM, Andrey wrote:

 Hello is there way to automatically generate documentation for 
 public methods, interfaces, fields etc.? e.g. now I should 
 write somethink like this to generate documentation for enum 
 Bacgkround:

 ///
 enum Background {
     transparent,  ///
     light,  ///
     dark,  ///
     action,  /// Background for action panel, e.g. with 
 buttons OK, Cancel etc.
 }


 
 I would like to write insted this:

 enum Background {
     transparent,
     light,
     dark,
     action,  /// Background for action panel, e.g. with 
 buttons OK, Cancel etc.
 }


 
 and avoid all redundant comments.


 Sorry, this isn't possible. Ddoc requires opt-in for public 
 documentation. The alternative would be opt-out, which would 
 look even worse I think.

 -Steve


I just added to dub.json this:


 "-ddoxFilterArgs": [
     "--min-protection=Public"
 ]


i.e. without --only-documented option, in this way ddox will 
generate documentation for all public methods, even if there is 
no docstring.
Nov 08 2017
parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 11/8/17 10:45 PM, Andrey wrote:


 I just added to dub.json this:
 

 "-ddoxFilterArgs": [
     "--min-protection=Public"
 ]


 
 i.e. without --only-documented option, in this way ddox will generate 
 documentation for all public methods, even if there is no docstring.


Interesting. I misunderstood then how ddox works. I thought the json it 
gets is the output from the ddoc generator, but now I realize it's the 
output from the parser itself.

So sure, this makes sense. Sorry for the misinformation!

-Steve
Nov 09 2017
parent reply RazvanN <razvan.nitu1305 gmail.com> writes:
On Thursday, 9 November 2017 at 14:21:52 UTC, Steven 
Schveighoffer wrote:

 On 11/8/17 10:45 PM, Andrey wrote:


 I just added to dub.json this:
 

 "-ddoxFilterArgs": [
     "--min-protection=Public"
 ]


 
 i.e. without --only-documented option, in this way ddox will 
 generate documentation for all public methods, even if there 
 is no docstring.


 Interesting. I misunderstood then how ddox works. I thought the 
 json it gets is the output from the ddoc generator, but now I 
 realize it's the output from the parser itself.

 So sure, this makes sense. Sorry for the misinformation!

 -Steve


I don't want to open a new forum thread for this, but if you guys 
have more experience with ddox can you please explain me how does 
it work? I expected you can simply run ddox on a .d file and it 
will output the documentation in some sort of form (json, html or 
whatever), but from what I saw, you need to pass it the json if 
you want to use serve-html/generate-html/filter and you have to 
use dmd to generate the json. Looking on the source code only 
passing serve-test actually parses the .d file, but the 
serve-test doesn't seem to be a public parameter.

Thanks in advance,
RazvanN
Nov 10 2017
next sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 11/10/17 5:12 AM, RazvanN wrote:

 On Thursday, 9 November 2017 at 14:21:52 UTC, Steven Schveighoffer wrote:

 On 11/8/17 10:45 PM, Andrey wrote:


 I just added to dub.json this:


 "-ddoxFilterArgs": [
     "--min-protection=Public"
 ]


 i.e. without --only-documented option, in this way ddox will generate 
 documentation for all public methods, even if there is no docstring.


 Interesting. I misunderstood then how ddox works. I thought the json 
 it gets is the output from the ddoc generator, but now I realize it's 
 the output from the parser itself.

 So sure, this makes sense. Sorry for the misinformation!


 
 I don't want to open a new forum thread for this, but if you guys have 
 more experience with ddox can you please explain me how does it work? I 
 expected you can simply run ddox on a .d file and it will output the 
 documentation in some sort of form (json, html or whatever), but from 
 what I saw, you need to pass it the json if you want to use 
 serve-html/generate-html/filter and you have to use dmd to generate the 
 json. Looking on the source code only passing serve-test actually parses 
 the .d file, but the serve-test doesn't seem to be a public parameter.
 


Just from observation, I see there's a generated json file when I use 
ddox. Since dmd can parse code and generate a .json file for a consumer 
to use, I assumed it was actually the result of ddoc, and ddox was just 
putting its own spin on it. But it seems the result of parsing all the 
code is generated in the json file.

I don't know much more than that, so I probably shouldn't have even 
responded in the first place :)

-Steve
Nov 13 2017
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 10 November 2017 at 10:12:32 UTC, RazvanN wrote:

 I don't want to open a new forum thread for this, but if you 
 guys have more experience with ddox can you please explain me 
 how does it work?


There's two modes of operation for ddox: using dmd -D -X to 
generate a json file, then making the documentation from that, or 
using libdparse to read the .d file itself and build docs from an 
AST. I know it used to default to the dmd json, but not sure if 
the default has changed since then to libdparse.

But the protection thing can work in either way: the dmd json 
output includes undocumented members too, so ddox can still 
generate a page for them if required.
Nov 13 2017
prev sibling parent Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Friday, 10 November 2017 at 10:12:32 UTC, RazvanN wrote:

 I don't want to open a new forum thread for this, but if you 
 guys have more experience with ddox can you please explain me 
 how does it work? I expected you can simply run ddox on a .d 
 file and it will output the documentation in some sort of form 
 (json, html or whatever), but from what I saw, you need to pass 
 it the json if you want to use serve-html/generate-html/filter 
 and you have to use dmd to generate the json. Looking on the 
 source code only passing serve-test actually parses the .d 
 file, but the serve-test doesn't seem to be a public parameter.


Not sure whether this is on topic, but does


 dub --build=ddox


do what you want?
Nov 13 2017