30 replies to this topic

[fincs]

Hello,

This is a complete rewrite of GenDocs 2.0. It now supports classes with methods, properties, constructors and embedded classes, as well as a Markdown-like syntax for formatting. There's even support for standalone custom pages!

For example: this script produces this output.

Download latest sources
Git repository

Don't forget to test!

[maul.esel]

:shock: :shock: :shock: cool.
I can't await to uninstall NDocs.

Can't test it today, but I will do tomorrow. Keep up the great stuff.

[maul.esel]

some minor comments:[*:7s4squpe]make GUI resizable ;-)
[*:7s4squpe]Are the ! at the beginning of the comment really necessary?
[*:7s4squpe]Some auto-detection feature of members or class ends would be coolI realize this is alpha, don't hurry

[Tuncay]

It looks so nice and clear, good work and thanks for this fincs. I will try this out soon.
@maul.esel
It is not meant as offending, wanted just share my thoughts about your points:
[*:1qdpu5d2]resizable GUI looks nice, but I don`t care, as I would use this in an automated way with the commandline (hope its possible!)
[*:1qdpu5d2]I can live with the bang. It makes it very clear, what comment should be parsed and what not. Its ok for me, if this helps the parser. Also, there could be some comments, which should not be showed in the documentation (in example describing implementation details and workarounds).
[*:1qdpu5d2]Auto detection of members and classes sounds difficult.
My first thoughts after looking shortly in the example:

1. Auto detection of "function header". The user should just note the name, instead all parameters in "Function: something(a, b [, c])". The parameters can be extracted from the function definition itself and formatted like you did in this example. Would be much nicer and less error prone for the one who writes the documentation and forget to update the header. Just a little thing less to think about.

2. What is "Throws:"?

3. My suggestion is, that it accepts any header. Only some predefined headers like "function:" and so on have special meaning, but if it encounters unknown header name, it should accept it too.

4. Inline HTML/CSS/JS would be cool to have.

5. I think I am only interested in standalone single html file pages.

[maul.esel]

@Tuncay[*:2j5ibss3]Yes, this was just the 1st thing I noticed ;-)
[*:2j5ibss3]It's okay, I'm just very lazy and don't want to rewrite all my NDocs comments
[*:2j5ibss3]This is something that I think is really important. I can't say how difficult it is, however, some regexs already exist (TillaGoTo maybe).And I guess "Throws" contains the exceptions that might be thrown ;-)

I think I am only interested in standalone single html file pages.

I really (would) like the possibility to define custom pages. But [*:2j5ibss3]it should be also possible to put it all in one file, as Tuncay suggested.
[*:2j5ibss3]I didn't look into your "page" keyword, but does it allow to define a new page from within the current document?I don't know anything about HTML, CSS, JavaScript etc (gonna learn this year ), but wouldn't there be the possibility to "simulate" pages without using separate files? Just a thought.

[fincs]

I would use this in an automated way with the commandline (hope its possible!)

Command line already supported 8)

GenDocs.ahk scriptFile.ahk

Are the ! at the beginning of the comment really necessary?

The bang is neccessary, because it signals GenDocs to process this comment. doxygen does exactly the same.

Some auto-detection feature of members or class ends would be cool

Auto detection of "function header".

Those aren't possible without a full-blown AHK parser. Sorry (I already tried to look into removing the "End of class" section, but I couldn't come up with anything.)

What is "Throws:"

And I guess "Throws" contains the exceptions that might be thrown

Exception throwing. The section is used to document the exceptions a function/whatever might throw.

My suggestion is, that it accepts any header.

I should really get that implemented. What would you like them to do? Currently it's nothing, they are ignored

Inline HTML/CSS/JS would be cool to have.

Indeed.

I think I am only interested in standalone single html file pages.

The way this new GenDocs is structured should make it easy to change the documentation generation backend.

I really (would) like the possibility to define custom pages.

Already supported, see Test Page.

but does it allow to define a new page from within the current document?

Yes:

/*!
	Page: Test Page
	Filename: TestPage
	Contents:
		# Your Markdown markup here
*/

but wouldn't there be the possibility to "simulate" pages without using separate files?

The markdown parser is there, it should be really easy to dump the generated HTML anywhere

[Tuncay]

Those aren't possible without a full-blown AHK parser. Sorry Sad (I already tried to look into removing the "End of class" section, but I couldn't come up with anything.)

Oh, if I think about it, you are right.

What is "Throws:"

Uh yes... I am silly!

About the "any header" implementation. I mean with any header the names with colon like "function:", "Filename:" ... I dont see any point why you should maintain explicitly so many header names. You have just a default handling, for unknown headers: Just convert the description to a paragraph without special fancy things, like in "Remarks:". Those who have special meaning, have special handling like "Page:".

I'm just very lazy and don't want to rewrite all my NDocs comments

A simple conversion script could help you.

I don't know anything about HTML, CSS, JavaScript etc (gonna learn this year Smile), but wouldn't there be the possibility to "simulate" pages without using separate files? Just a thought.

The reason for support of inline HTML and CSS (and probably, just probably JavaScript) is not to create new pages. It allows some simple structures you have in your mind, without GenDocs handling. In example, you need a table and GenDocs have no support for tables, but HTML. You just create a HTML Table and integrate it. Thats all. Or you just use some markups like <b> or other stuff.

Just an idea how it could look: Look whole block for html

/*!HTML
	Library: Test library, version 1.0
		This library does something
		
		or maybe not!  
		<i style="">In</i>-paragraph line breaks work
	Author: fincs
	License: WTFPL
*/

Or there is a settings header for HTML, to enable or disable (positional) without need for marking each comment block.

	/*!
	Settings: HTML=1, KEY=0
	*/
	/*!
	Library: Test library, version 1.0
		This library does something
		
		or maybe not!  
		<i style="">In</i>-paragraph line breaks work
	Author: fincs
	License: WTFPL
*/

Off course, HTML is excluded from code sections. These are just some brainstorming thoughts and not deliberate wishes.

[fincs]

Just an idea how it could look: Look whole block for html
(...)
Or there is a settings header for HTML, to enable or disable (positional) without need for marking each comment block.

I like the idea
BTW, what does KEY=0 mean?

[Tuncay]

You can see "KEY=0" as "something". I wanted show only a comma listed key=value system. It could use CSV as in example. Just replace "KEY" with "something" you need. But I am not sure, if such a settings block is really good for the future. It makes the source documentation dependent to a specific / to your tool.

I just found some minutes to test it. I cant say much now, but it should get rid of the "End of class" declaration! The generated doc looks really nice.

[Tuncay]

I just found out, the indentation of headers (like "Constructor:") are important. Is this by design? Also found out, if a line ends with two spaces, a newline is generated in the html. Same in Firefox and Internet Explorer.

If you like, look at my library para - Paragraph beautifier (a text formatter) for text (not code).

Also I miss a header for ErrorLevel. (Could be easily solved with "any header" support.)

[fincs]

the indentation of headers (like "Constructor:") are important. Is this by design?

Yes, although you should be able to use any type of indentation. I think that even nothing is supported as indentation for the header lines, haven't tested it out though

/*!
Function: whatever(...)
    Blah blah blah
...
*/

Also found out, if a line ends with two spaces, a newline is generated in the html. Same in Firefox and Internet Explorer.

That is part of the Markdown spec: if a line ends with two spaces, it should generate a <br/>.

If you like, look at my library para - Paragraph beautifier (a text formatter) for text (not code).

I don't see how it could be used. Text indentation is done through CSS, and the rest is done automatically by the rendering engine AFAIK...

[Tuncay]

A new icon could be made. I suggest an exclamation mark as main identification symbol. I try to make one, if I find time and post it here, if it looks usable.

[Tuncay]

I would like to describe and list the member this.variables in the Class description. Like in this example (not sure what the correct terminology is, member variables or whatever):

/*!
    Class: MyClass
        This is a description.
    Variables:
        path - contains the file path associated with the object.
        data - the bare data.
    Example: @file:myclass_example.ahk
*/

Or is there any other place where these should be put to? Also a Remarks section should be there too. I like your tool. It is going to replace Natural Docs. Hope it gets the standard in our community. I would encourage everyone to use it!

[fincs]

Also I miss a header for ErrorLevel.

Obsoleted by throw

I would like to describe and list the member this.variables in the Class description.
...
Also a Remarks section should be there too.

You can do all of that already: (gen'd HTML)

/*!
    Class: MyClass
        This is a description.
    Extra:
        ## Remarks
        Your remarks go here
    Example: @file:myclass_example.ahk
    @UseShortForm
*/

/*!
    Property: path [get/set]
        Contains the file path associated.
*/

/*!
    Property: data [get/set]
        The bare data.
*/

/*!
    End of class
*/

I do agree though that it would be a good idea to have the Class docu generator support the Remarks section. I'll add it

It is going to replace Natural Docs. Hope it gets the standard in our community. I would encourage everyone to use it!

Thank you for your support! :oops:

[Tuncay]

Oh I missed that part. I will have a closer look.

About ErrorLevel. It is part of AutoHotkey and what if someone with AutoHotkey prior to 1.1 want use your documentation tool? We have many users who use Basic still... you know. And what if someone is new to AHK and do not want to use Throw. Also, I have my own usage with ErrorLevel still. It is not obsolete, so please support it!

In example, if Throw is used, the function have to use Try... Catch block. Otherwise he gets a runtime Error. But I like to describe errors through ErrorLevel, if they are not that important. The script can work still and will not be aborted then.