last day (14 days later) » 

11:42 AM
1
Q: Looking for a (generic) source code documentation tool for Dart

corgrathI am looking for source code documentation tool that can be used for Dart code, or a generic tool that can understand JavaDoc-similar syntax in source code. (Dart's docgen is just for when developing API libraries and not for your solution) Are there any Dart specific or generic doc tool?

 
Can you be a bit more specific what features you are missing in docgen?
 
docgen doesn't cover all of your code, only your libraries. The tagline of docgen is "The API Documentation Generator", the docs says "Docgen generates documentation from Dart code in the lib directory and creates the output in JSON format.". I am looking for a source code documentation for all of my source code.
 
Usually almost all code can or should be in lib. Of course example, tool, test are some of the exceptions but bin or web should contain only the entry page and the main method. Did you create a feature request for docgen?
 
"Usually almost all code can or should be in lib" -- um, why? I have my code in a folder called "src", and thats pretty common for most software projects. "libs" are usually for third party libraries your software uses. "Did you create a feature request for docgen?" -- nope (why should we?)
 
There are Pub Package Layout Conventions src in the package root is not a proper source code directory (src inside one of the listed top level directories is fine though). Having your implementation code in lib is not mandatory in general but it is implied by several tools (for example DI or Angular transformer or docgen). "Feature request": if you don't tell them your requirements how should they consider them?
 
11:42 AM
"There are Pub Package Layout Conventions src in the package root is not a proper source code directory " -- right, but as I wrote, I am not writing a pub package, but full software solution. ""Feature request": if you don't tell them your requirements how should they consider them?" -- true, but the thought never crossed me to make a feature request to ask them to redefine the purpose of their tool.
@GünterZöchbauer docgen is a tool to generate documentation for your pub package, not for your software application. there is a difference there.
 
When you build an Angular app you also create a full software solution not a library. This is usually no reason to deviate from the package layout contentions. Also tools like pub build (dart2js, dart2dart) will probably cause problems when your code layout is unexpected.
sure
Hi
 
I think you have misunderstood the purpose of me asking for a source code documentation tool. It is not for generating a doc for a dart pub package library.
 
I have troubles to understand why you think an application is not a pub package.
 
With other words, you have problems understanding the difference between libraries and applications?
 
11:45 AM
But you think an application is a library?
 
the troubles are 'why do you think an application is not a pub package' :)
 
pub is Darts package manager. Why would an application ever be labeled as a library?
 
as I wrote in one of my first comments in an application you have a main() usually in bin for cosole/server app or web for browser app. Everything else can be in lib
 
So, given Windows was written in Dart. You think its strange it is not designed according to a pub package library?
 
and you import the current package into the main.dart file and use your application implementation like a library package
 
11:47 AM
You can answer my Windows question first, please.
 
hmm, Windows is maybe not a good example ;-) what about Word?
 
Sure, Word.
 
sure, you should create it as a pub package
no need to publish if you don't want to
 
Right, ok.
 
Your first requirement for a Dart app is a directory containing a pubspec.yaml and from then on its a pub package
 
11:50 AM
In the docs, it says "When you build a pub package, we have a set of conventions we encourage you to follow."
Not even Google agrees with you Gunter.
This is not a Dart application convention you are speaking of, its conventions when writing pub packages.
 
but you have a pubspec.yaml in the root of your dart application?
and you probably use pub build?
 
I have a pubspec in order to use third party packages yes.
 
the only difference I see between a library package and and application package is that an application package has an entry point used to launch the application (the main method)
 
okay
I dont agree with you.
 
there is for example the new pub global command that allows you to register a Dart script globally so you can run it using pub run package_name:script_name which depends on the package layout
why do you disagree?
 
11:56 AM
Now its mainly principle, because you have a view how software development should be done and if it is not according to your view, its wrong.
There is nothing from Google saying that having "lib" as your source code folder is a convention for a non-pub package.
 
hmm, I just try to save you troubles you may encounter later
 
And if you look at other software languages and platforms, there its common to make that differentiation.
No, sorry Gunter. You tried to convert me into thinking according to you, even in a stackoverflow question.
Pulling up documentation from Google, when it clearly specifies this is a convention when developing libraries for their package management system, and then saying this is the norm, makes no sense.
 
The pub layout convention are not mandatory for Dart (as a language) they are not even mandatory for the pub tool but they are recommended and I encountered troubles already because for Angular it is a requirement.
 
Angular is used an a library
as*
 
yes but for building an application
you usually don't need Angular for building a library
 
12:00 PM
Angular is a library / framework. As I wrote before, there is a difference between a library and a full application.
 
(beside building angular widgets)
 
I will get very personal now Gunter, but I think you have only used Dart as a language and a platform?
 
yes, but when you use Angular in your application then Angular requires that your application code layout is according to the package layout convention.
then help me to understand what you do differently
 
it depends on the software
 
what kind of application do you build?
 
12:02 PM
NDA
can you give me an example of an application that uses this setup?
 
you can't tell if it is a web app, a server app, a desktop app with a GUI or a command line tool?
 
or conventions
 
each kind of application of the just mentioned kinds
 
Word?
or what application?
give me an example, please
 
ok, when we stick to this example
you have a word directory with a pubspec.yaml
 
12:05 PM
no, please. Give me an example of an application that uses this convention.
doesn't have to be Dart and pub, any other languages / platform will do.

I am curious about some examples.
 
there are not so many Dart applications out there (in fact I don't know any besides Spark). Can you give me an example of an application that doesn't?
but this is specific to Dart only
 
Okay, lets say Dart.
 
in fact not specific to Dart but specific to pub
 
Let me just see if i can find something quickly.
No, we have to be at the right level. Dart.
You want to convert all solutions, written in Dart, to be according to pub conventions.
 
I'm pretty sure most of them already are
 
12:10 PM
Here is a sample given from Google itself, not using that convention:

https://code.google.com/p/dart/source/browse/branches/bleeding_edge/dart/samples/#samples%2Fdcat
 
you are busy looking?
 
Their code is located in a "bin" folder, not a "lib" according to Pub dart conventions.
 
hmm, couldn't find any *.dart file in this example
 
okay, there is a dcart.dart
 
12:14 PM
Dartiverse Search, server side application sample from dart
Okay Gunter, I dont have time anymore. I hope you learned the world isn't as square as you thought :-)
 
same to you ;-)
 

last day (14 days later) »