shadcn_flutter icon indicating copy to clipboard operation
shadcn_flutter copied to clipboard
verified publisher icon sunarya-thito

Code documentation

Open sunarya-thito opened this issue 1 year ago • 11 comments

Some APIs/Widgets are missing documentation. (At least 20% of the code need to have documentation, but I'm aiming for more).

sunarya-thito avatar Jul 20 '24 20:07 sunarya-thito

Hi, I'll be glad to help with this, I keep coming to part of the code that I have to read to know what the default value of something is or what does it throw, so I might as well write it and make a pull request.

Is there a specific format that you want the documentation to be written in? or a specific information that should be present between all documentations?

MoathCodes avatar Aug 04 '24 20:08 MoathCodes

Hi, I'll be glad to help with this, I keep coming to part of the code that I have to read to know what the default value of something is or what does it throw, so I might as well write it and make a pull request.

Is there a specific format that you want the documentation to be written in? or a specific information that should be present between all documentations?

I don't really have anything in mind when it comes to documentation format. I have not really looked into what a good dart code documentation looks like. Do you have any suggestions?

sunarya-thito avatar Aug 04 '24 23:08 sunarya-thito

I actually don't know as well, I think sticking to what is recommended by Dart is a good starting point. https://dart.dev/effective-dart/documentation

the rules they list are simple to follow.

MoathCodes avatar Aug 05 '24 08:08 MoathCodes

Yeah I think we can follow that guide. There's a lot of functions, vars, and classes but we need to prioritize public API first. Let me know if you need anything else.

sunarya-thito avatar Aug 06 '24 17:08 sunarya-thito

Any chance you could make the text in the documentation selectable text? Not just the code blocks. :)

Brianelvio avatar Sep 17 '24 20:09 Brianelvio

Any chance you could make the text in the documentation selectable text? Not just the code blocks. :)

is there any reason to?

sunarya-thito avatar Sep 18 '24 00:09 sunarya-thito

Any chance you could make the text in the documentation selectable text? Not just the code blocks. :)

is there any reason to?

Would just help me out in my workflow of leaving notes/comments in code :) I'll get it from the repo if it's a hassle. Just so used to being able to copy documentation text lol.

Brianelvio avatar Sep 23 '24 20:09 Brianelvio

Any chance you could make the text in the documentation selectable text? Not just the code blocks. :)

is there any reason to?

Would just help me out in my workflow of leaving notes/comments in code :) I'll get it from the repo if it's a hassle. Just so used to being able to copy documentation text lol.

Ah understandable, let me see what I can do

sunarya-thito avatar Sep 24 '24 03:09 sunarya-thito

Docs Link The documentation link here is not loading. Tried in chrome.

Update 1: Works in brave!! Maybe a cache issue but cleared cache still chrome is not load for me. Loading Application Splash screen.

adds08 avatar Feb 18 '25 05:02 adds08

I have a few documentation contributions to make, but before opening up any PR(s) I tried to generate the API docs locally using dart doc. This results in the following error:

Initialized dartdoc with 1919 libraries
Generating docs for library shadcn_flutter_extension.dart from package:shadcn_flutter/shadcn_flutter_extension.dart...
Generating docs for library shadcn_flutter.dart from package:shadcn_flutter/shadcn_flutter.dart...

dartdoc 8.3.1-wip (/home/cranston/workspace/shadcn_flutter/dartdev) failed: UnimplementedError: No members on Library.sentinel are accessible
#0      _LibrarySentinel.noSuchMethod (package:dartdoc/src/model/library.dart:18:7)
#1      _LibrarySentinel.element (package:dartdoc/src/model/library.dart:15:7)
#2      canonicalLibraryCandidate (package:dartdoc/src/model/canonicalization.dart:13:69)
#3      ModelElement.canonicalLibrary.<anonymous closure> (package:dartdoc/src/model/model_element.dart:509:11)
#4      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart:524:4)
#5      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart)
#6      PackageGraph.findCanonicalModelElementFor (package:dartdoc/src/model/package_graph.dart:726:32)
#7      DefinedElementType.isPublic (package:dartdoc/src/element_type.dart:303:22)
#8      IterableOfNameableExtension.wherePublic.<anonymous closure> (package:dartdoc/src/model_utils.dart:86:49)
#9      WhereIterator.moveNext (dart:_internal/iterable.dart:468:13)
#10     MappedIterator.moveNext (dart:_internal/iterable.dart:419:19)
#11     WhereTypeIterator.moveNext (dart:_internal/iterable.dart:904:20)
#12     Constructable.extraReferenceChildren (package:dartdoc/src/model/inheriting_container.dart:35:14)
#13     Container.referenceChildren (package:dartdoc/src/model/container.dart:202:8)
#14     _rejectUnnamedAndShadowingConstructors (package:dartdoc/src/markdown_processor.dart:151:10)
#15     CommentReferable._recurseChildrenAndFilter (package:dartdoc/src/model/comment_referable.dart:159:23)
#16     CommentReferable._lookupViaScope (package:dartdoc/src/model/comment_referable.dart:144:12)
#17     CommentReferable.referenceBy (package:dartdoc/src/model/comment_referable.dart:58:20)
#18     _getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:176:15)
#19     getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:187:16)
#20     MarkdownDocument._makeLinkNode (package:dartdoc/src/markdown_processor.dart:313:18)
#21     new MarkdownDocument.withElementLinkResolver.<anonymous closure> (package:dartdoc/src/markdown_processor.dart:267:51)
#22     LinkSyntax._resolveReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:137:36)
#23     LinkSyntax._tryCreateReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:177:18)
#24     LinkSyntax.close (package:markdown/src/inline_syntaxes/link_syntax.dart:103:12)
#25     InlineParser._linkOrImage (package:markdown/src/inline_parser.dart:150:32)
#26     InlineParser.parse (package:markdown/src/inline_parser.dart:106:9)
#27     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:298:67)
#28     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:303:9)
#29     MarkdownDocument.parseMarkdownText (package:dartdoc/src/markdown_processor.dart:288:5)
#30     Documentation._parseDocumentation (package:dartdoc/src/model/documentation.dart:83:21)
#31     Documentation._renderDocumentation (package:dartdoc/src/model/documentation.dart:64:23)
#32     Documentation.asOneLiner (package:dartdoc/src/model/documentation.dart:58:5)
#33     ModelElement.oneLineDoc (package:dartdoc/src/model/model_element.dart:709:49)
#34     _renderCategory_partial_container_3 (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:2908:25)
#35     renderLibrary (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:958:20)
#36     HtmlAotTemplates.renderLibrary (package:dartdoc/src/generator/templates.dart:178:30)
#37     GeneratorBackend.generateLibrary (package:dartdoc/src/generator/generator_backend.dart:186:29)
#38     HtmlGeneratorBackend.generateLibrary (package:dartdoc/src/generator/html_generator.dart:80:11)
#39     GeneratorFrontEnd._generateDocs (package:dartdoc/src/generator/generator_frontend.dart:158:27)
#40     GeneratorFrontEnd.generate (package:dartdoc/src/generator/generator_frontend.dart:37:25)
<asynchronous suspension>
#41     Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:203:5)
<asynchronous suspension>
#42     Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:241:24)
<asynchronous suspension>
#43     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:273:9)
<asynchronous suspension>

I noticed that when I comment out this line the error goes away as far as dart doc goes. Obviously this breaks compilation, but suggests where the underlying issue lies.

The generated API documention on pub.dev seems just fine so I'm not sure what exactly is going on.

Is this a known issue?

cranst0n avatar Feb 24 '25 22:02 cranst0n

I have a few documentation contributions to make, but before opening up any PR(s) I tried to generate the API docs locally using dart doc. This results in the following error:

Initialized dartdoc with 1919 libraries
Generating docs for library shadcn_flutter_extension.dart from package:shadcn_flutter/shadcn_flutter_extension.dart...
Generating docs for library shadcn_flutter.dart from package:shadcn_flutter/shadcn_flutter.dart...

dartdoc 8.3.1-wip (/home/cranston/workspace/shadcn_flutter/dartdev) failed: UnimplementedError: No members on Library.sentinel are accessible
#0      _LibrarySentinel.noSuchMethod (package:dartdoc/src/model/library.dart:18:7)
#1      _LibrarySentinel.element (package:dartdoc/src/model/library.dart:15:7)
#2      canonicalLibraryCandidate (package:dartdoc/src/model/canonicalization.dart:13:69)
#3      ModelElement.canonicalLibrary.<anonymous closure> (package:dartdoc/src/model/model_element.dart:509:11)
#4      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart:524:4)
#5      ModelElement.canonicalLibrary (package:dartdoc/src/model/model_element.dart)
#6      PackageGraph.findCanonicalModelElementFor (package:dartdoc/src/model/package_graph.dart:726:32)
#7      DefinedElementType.isPublic (package:dartdoc/src/element_type.dart:303:22)
#8      IterableOfNameableExtension.wherePublic.<anonymous closure> (package:dartdoc/src/model_utils.dart:86:49)
#9      WhereIterator.moveNext (dart:_internal/iterable.dart:468:13)
#10     MappedIterator.moveNext (dart:_internal/iterable.dart:419:19)
#11     WhereTypeIterator.moveNext (dart:_internal/iterable.dart:904:20)
#12     Constructable.extraReferenceChildren (package:dartdoc/src/model/inheriting_container.dart:35:14)
#13     Container.referenceChildren (package:dartdoc/src/model/container.dart:202:8)
#14     _rejectUnnamedAndShadowingConstructors (package:dartdoc/src/markdown_processor.dart:151:10)
#15     CommentReferable._recurseChildrenAndFilter (package:dartdoc/src/model/comment_referable.dart:159:23)
#16     CommentReferable._lookupViaScope (package:dartdoc/src/model/comment_referable.dart:144:12)
#17     CommentReferable.referenceBy (package:dartdoc/src/model/comment_referable.dart:58:20)
#18     _getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:176:15)
#19     getMatchingLinkElement (package:dartdoc/src/markdown_processor.dart:187:16)
#20     MarkdownDocument._makeLinkNode (package:dartdoc/src/markdown_processor.dart:313:18)
#21     new MarkdownDocument.withElementLinkResolver.<anonymous closure> (package:dartdoc/src/markdown_processor.dart:267:51)
#22     LinkSyntax._resolveReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:137:36)
#23     LinkSyntax._tryCreateReferenceLink (package:markdown/src/inline_syntaxes/link_syntax.dart:177:18)
#24     LinkSyntax.close (package:markdown/src/inline_syntaxes/link_syntax.dart:103:12)
#25     InlineParser._linkOrImage (package:markdown/src/inline_parser.dart:150:32)
#26     InlineParser.parse (package:markdown/src/inline_parser.dart:106:9)
#27     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:298:67)
#28     MarkdownDocument._parseInlineContent (package:dartdoc/src/markdown_processor.dart:303:9)
#29     MarkdownDocument.parseMarkdownText (package:dartdoc/src/markdown_processor.dart:288:5)
#30     Documentation._parseDocumentation (package:dartdoc/src/model/documentation.dart:83:21)
#31     Documentation._renderDocumentation (package:dartdoc/src/model/documentation.dart:64:23)
#32     Documentation.asOneLiner (package:dartdoc/src/model/documentation.dart:58:5)
#33     ModelElement.oneLineDoc (package:dartdoc/src/model/model_element.dart:709:49)
#34     _renderCategory_partial_container_3 (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:2908:25)
#35     renderLibrary (package:dartdoc/src/generator/templates.aot_renderers_for_html.dart:958:20)
#36     HtmlAotTemplates.renderLibrary (package:dartdoc/src/generator/templates.dart:178:30)
#37     GeneratorBackend.generateLibrary (package:dartdoc/src/generator/generator_backend.dart:186:29)
#38     HtmlGeneratorBackend.generateLibrary (package:dartdoc/src/generator/html_generator.dart:80:11)
#39     GeneratorFrontEnd._generateDocs (package:dartdoc/src/generator/generator_frontend.dart:158:27)
#40     GeneratorFrontEnd.generate (package:dartdoc/src/generator/generator_frontend.dart:37:25)
<asynchronous suspension>
#41     Dartdoc.generateDocsBase (package:dartdoc/src/dartdoc.dart:203:5)
<asynchronous suspension>
#42     Dartdoc.generateDocs (package:dartdoc/src/dartdoc.dart:241:24)
<asynchronous suspension>
#43     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/src/dartdoc.dart:273:9)
<asynchronous suspension>

I noticed that when I comment out this line the error goes away as far as dart doc goes. Obviously this breaks compilation, but suggests where the underlying issue lies.

The generated API documention on pub.dev seems just fine so I'm not sure what exactly is going on.

Is this a known issue?

not sure about this one, the dart doc on the pubdev it self also failed to generate but it was a different issue

sunarya-thito avatar Feb 28 '25 04:02 sunarya-thito