Sublime Forum

DoxyDoxygen: An alternative to DocBlockr

#1

DoxyDoxygen (github.com/20Tauri/DoxyDoxygen) is a new alternative to DocBlockr.

Advantages:

  • C#, Ruby, Swift, Python support
  • C, C++ support is really better than the dedicated plugin DoxyDoc (since I’ve written this post DoxyDoc is “trending”, strange :wink: )
  • Capability to update existing comments
  • Provide type guessing based on body inspection (for Php and Java)
  • Provide plugin supports to extend it
  • Enhanced comment folding

If you try it, I really interested in your feedback

3 Likes

#2

Hi, it looks like you put a lot of work into it.

I’m surprised that you need to parse the language to generate the doc.
I recently created a toy plugin to generate C# doc and I used the scopes from the sublime-syntax. The whole think is less than 100 lines without dependencies.

That said, I really like the update feature, really useful when you add a parameter to a method.

Also could we choose to use /// instead of /** in C# ?

0 Likes

#3

Hi,

Some languages like JavaScript, Php, Python provide dynamic types checking…
In the demo, you can see that “{number}” (the parameter type) is automaticly setted. I need to parse the whole body to do this.
Another reason, I don’t directly use SublimeText syntax is because they may differ from one language to another, they may also change from one version to another one. And syntaxes may also be override by installed packages… This approach seem harder to debug for a non personnal use… But syntaxes are now “in the community”, and things will probably be better

I use sublime syntaxes only for “CommentNearestEntity” functionnality… I’ve experimented some issues (even with common languages like Php…).
I like “CommentNearestEntity”. Pressing Alt+Q after a function declaration to document it is more efficient than go back and open a new comment.

Yes, you may choose comment style… You have to edit settings to do it… Simply put the style ("///", “///”) at the beginning of the prefered styles list.

Tips: From the palette, “select all comments” and “update (comment style)” is an easy way to change the documentation style of a whole file.

Thank you for your feedback

0 Likes

#4

Because a lot of people request on DocBlockr GitHub features included in DoxyDoxygen, you may found here a short side by side comparaison.
https://github.com/20Tauri/DoxyDoxygen/blob/master/COMPARE.md

If you find others differences, please let me know, I will update this file.

0 Likes

#5

Thanks, but I don’t want to use /// on java for example, just on C# can you do this per language ?
Also with “///”, “///” my comments look like:

        ///
        /// <summary>< function_description ></summary>
        ///
        /// <param name="dirPath">< description ></param>
        ///

while i was expecting:

        /// <summary>< function_description ></summary>
        ///
        /// <param name="dirPath">< description ></param>

It would be nice if I could use “”, “///” as settings to specify that I don’t need a first line comment

0 Likes

#6

You cannot currently change the commenting style per language… But I will allow to override “prefered_comments_styles” and “block_layout” per “profile” in a next release.

Right now, you may remove the extras blank lines… In DoxyDoxygen user setting, edit “block_layout” -> “XmlDoc”… You may choose blank line and location / generated fields…

Result should look like

        "XmlDoc": 
            "<summary>",
            "",
            "<paramref",
            "<param",
            "",
            "<returns>",
            "",
            "<exception"
        ],

It’s also a way to add fixed (like author) or generated fields (like dates)… See “block_layout” -> “Doxygen” for example
As your notation is the C# recommended one, it will be the default in next release.

Thanks for using this plugin

0 Likes

#7

An idea: as DoxyDoxygen try to preserve commenting style.
If you type “///” and press Alt+Q you will have the expected behaviour for C# without changing your configuration
You simply have to put a specific trigger ENTER on context “///”, call the Alt+Q function… Job done !

… or wait for a future version

0 Likes

#8

Current version have now your expected behaviour with default settings

0 Likes

#9

Today, a short tutorial in slovak has been created:

… and the official documentation has been updated (with tips)

0 Likes

#10

Is there a list of “parsers” that can be used when defining your own profiles and block layouts. So far every attempt to make my own (i.e. JavaDoc) causes a fatal error with a report.

0 Likes

#11

Available doc-styles are:

  • ApiDoc
  • AsDoc
  • Base
  • Doxygen
  • Drupal
  • GoogleClosure
  • JavaDoc
  • JsDoc
  • PhpDoc
  • SassDoc
  • Sphinx
  • XmlDoc
  • YuiDoc

You can extend DoxyDoxygen by plug-ins. Available doc-styles using plug-in are:

  • HeaderDoc

Available parsers are:

  • LanguageBase
  • LanguageBash
  • LanguageCpp
  • LanguageCSharp
  • LanguageGeneric (support more than 40 programmings languages)
  • LanguageJava
  • LanguageJavaScript
  • LanguageJson
  • LanguagePhp
  • LanguagePython
  • LanguageRust
  • LanguageSwift

List of support langguages may be found here: http://20tauri.free.fr/DoxyDoxygen/v2/page_appendices.php#supported-languages

As JavaDoc is “default” doc_styles, you probably write something wrong in your “profiles” settings.
Or switch “parsers” and “doc_styles”

"profiles": [
{
    "languages":  [ "java" ],           # sublime text signature
    "parsers":    [ "LanguageJava" ],   # parsers names, first is best
    "doc_styles": [ "JavaDoc" ],        # doc_styles names, first is main one, others are only used to add "completions"
}
0 Likes

#12

Additionnal informations (because this topic is really old)

DoxyDoxygen now also provide:
- inline translation services (bing, google, yandex, baidu, yaidu, mymemories, hablaa…)
- smart description generation
- documentation generation
- Python docstring support
- Php FQN (Fully Qualified Name) support
- …

0 Likes

#13

Just tried this and I’m stunned at how comprehensive this package is. Amazing work!!!

0 Likes

#14

What is https://packagecontrol.io/packages/DocBlockr_with_update_capability ? It looks like DoxyDoxygen, the Menu entries, settings and everything else refers to DoxyDoxygen.

0 Likes

#15

It’s the same package, but with a different name. Entries here.

I’m strongly opposed to allowing package aliases like this and the submission was not reviewed because it was inside a custom repository. Unless @wbond and @ThomSmith would like to allow aliases, @20tauri, please refrain from submitting your package more than once and remove the alias. You can of course add a previous_names entry in your DoxyDoxygen package to have users of the aliased package continue receiving updates from the actual package.

0 Likes

#16

Initially the package was slightly different in shortcuts (to match DocBlockr).
Because it was hard to maintain, now the binairies release is the same.
I’ve hesitated to remove it, but kept it because the alias is more used than the official name.

I agree @FichteFoll, if everybody duplicate entries. It will be a nightmare…
I have just removed the alias… Will desappear on next Package Control refresh

1 Like

#17

By the way, instead of a separate package in DoxyDoxygen (evolution) I suggest using the pre-release feature. Users can then opt into having Package Control install pre-releases through PC’s setting (install_prereleases). You just need to add another release to the package’s releases with a pre-release version. Refer also to https://semver.org.

1 Like

#18

Thanks. This recommendation cannot be applied directly.
I need to release a 1.0.0 first according Package Control Documentation

Package control not seem to highlight that a prerelease exist for a package.
Not really convenient for final users.
To find a package that implement this feature I have query the package control cache (may be because I miss something).

For example, this feature is used by “Rust Enhanced”.

    {"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v2.11.0", "version": "2.11.0", "date": "2018-04-22 11:21:44"}, 
    {"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v2.11.0-prerelease", "version": "2.11.0-prerelease", "date": "2018-04-22 11:21:44"},
    {"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v2.10.0", "version": "2.10.0", "date": "2018-03-02 11:16:28"},
    {"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v2.8.0", "version": "2.8.0", "date": "2018-01-28 16:20:50"},
    {"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v1.3.2", "version": "1.3.2", "date": "2017-05-04 19:22:33"},
    {"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v1.2.5", "version": "1.2.5", "date": "2017-03-16 12:35:12"},

In this example, I don’t understandand why “url” is different for “release” and “final version”
I also don"t understand the benefict of referencing old versions.

0 Likes

#19

It does show on the package info page on https://packagecontrol.io, but only if a prerelease exists. In order to prompt users to use the testing version, you have to inform them yourself via update messages or the readme, for example. The number of packages that use prereleases is fairly small.

I don’t understand what you mean with this.

Iirc it was indended to allow for downgrades and to provide the client PC enough freedom to select an eligible version in case of version or platform restrictions. As far as I understand, it is rarely used but it doesn’t hurt providing old releases.

0 Likes

#20

For the second point, in the following example I don’t understand why “https://codeload.github.com/rust-lang/sublime-rust/zip/v2.11.0-prerelease” is not simply “https://codeload.github.com/rust-lang/sublime-rust/zip/v2.11.0”.

{"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v2.11.0", "version": "2.11.0", "date": "2018-04-22 11:21:44"}, 
{"sublime_text": ">=3000", "platforms": ["*"], "url": "https://codeload.github.com/rust-lang/sublime-rust/zip/v2.11.0-prerelease", "version": "2.11.0-prerelease", "date": "2018-04-22 11:21:44"},

I suppose that Package Control will prefer 2.11.0 instead of -prelease when exist.
I also suppose that the both “url” may be the same. Even if there’s no reason to to that

Is the following live cycle correct ?
From a 1.0.0, I want to do a beta. I create a 1.0.1-prerelease. When beta validated, I remove the “-prelease” suffixe. All users will have the same version (no longer need to preserve the prerelease entry)

Thanks again for all those suggestions and informations !

0 Likes