de-jcup / code2doc Goto Github PK
View Code? Open in Web Editor NEWCreate documentation by code
License: Apache License 2.0
Create documentation by code
License: Apache License 2.0
What about concepts knowing use cases? And what about linking from text to use cases?
Currently only use cases know the concepts (reason was that a use case can simple removed and this has no effect to architecture it self)
When internal links are possible (see #6)
we should create a validator for internal links too - otherwise only at rendering time a wrong code2doc://-link will trigger errors on rendering engines (like docbook4j - fo etc.)
Currently inside a document following ordering happens:
UC_USERS_2_USERS_OVERVIEW
UC_USERS_1_USERS_SHOWLIST
But it must be
UC_USERS_1_USERS_SHOWLIST
UC_USERS_2_USERS_OVERVIEW
Also it would be possible to write extensions for this.
Idea would be like:
code2doc-extension-utils
=> EntityModelPictureCreator.createClassDiagramPictureFor(YourProject.class);
see also #20
Ordering output of elements in rendered document must be alphabetical ascending
e.g.
UC_1.class
UC_2.class
UC_3.class
must always have this ordering.
UC_1, UC_2, UC_3 !
ERROR main - resource not found for resource path:myTasks.png
does result only errors in log but no explicit runtime exception.
Instead only freemarker template does result in error:
FreeMarker template error:
The following has evaluated to null or missing:
==> transformer.transformToFile(useCase.examplePictureResourcePath) [in template "macro/usecase.ftl" at line 55, column 45]
Currently Specificaiton is representing a write only interface, so no unnecessary getters are available (does not confuse...)
But for custom generators there must be something like
ReadableSpecification
or maybe simple : SpecificationModel ?
Anyway.. the interface should only support read methods (as currently used by the FTL types directly to specification impl). Normaly only these calls must be transfered to interfaces.
This is a little bit familiar with #35
What about a wiki content grabber? or any other project content grabber?
Some projects could define their content already in a wiki - its very easy to use, smooth and normally has wyswig editors etc.
So the idea would be to make an Code2DocExtension available for projects where they could provide
wiki content.
Would this be nice?
For markup HTML
Currently its too difficult/verbose to describe documentation via code.
It should be much simpler. Also the describing of text should be done nearly only via markdown or asciidoctor (TBD).
Currently the collection of annotated enums results in simple addLinkToURL in tech info but not in addLinkToJava(id, enum)
So the transformer is not able to handle enums correctly in output when transformToString is called in templates
currently when you got an image and you want it inside your described text you must divide
text into different files and add it into use case def...
e.g.
content().addTextResource("resource1.html").addPictureResource("picture1.png").addTextResource("resource2.html").
very ugly to use...
Write a extension to do auto scnapshots for use cases where example url is set!
/**
* @return path or <code>null</code> if no snapshot can be created for given object
*
*/
public String createExampleURLSnapshot(Object object)
This should be an abstract implementation so only dedicated file names etc. are possible. The handling itself (e.g. using Selenium-Test-APi to get snapshots must be done in projects itself!)
A snapshot file renderer should do the internal parts like add to to model etc.
In some projects the original concepts are done in tracking systems like JIRA.
Maybe it would be nice to have a semantic part like
setup.addLinkToIssue(#18) ?
We have done this before for wiki entries
(setup.setWikiURL(..) )
Currently e.g. Specification impl is being very ugly implented - needs to be refactored.
Every impl should have a dedicated hashcode equals (and maybe a to string impl)
In use cases the setup is able to do:
setup.addRole(Role r)
setup.addRole(Role r, Constraint c);
Should be Like in UseCase:
protected void doSetup(UseCaseSetup setup){
setup.setExamplePictureResource(...)
}
=>
protected void doSetup(ArchitectureSetup setup){
setup.setBigPictureResource(...)
}
Purpose is to have a dedicated position in document for such kind of pictures.
(A big picture should always give you straight forward view of the architecture)
alphabetical ordering in a tech info table (by its type) would be more readable - and type parts could be groupd also.
This is a discussion issue about missing features in code2doc. In lack of a forum all issues labeled with "discussion" are used to handle this kind of messaging.
👍
Currently when an error happens we got a error log entry, an outpt error marker entry instead of correct one... and also and xml comment about the error.
the comments are using -- which is not allowed inside xml comments itself
on the other side it makes no senso to add comments when its also inside the ouptut.
So remove the comments.
Currently locale=null means default language (like in resource bundles).
while defining content in a setup this okay. But inside generation getContent() should use not null but setDefaultLocale instead (and this could be used by generator)
so we could remove getContent(Locale) completely!
Advantage: no more changes necessary for freemarker templates - thiese must only use content...
E.g.
so developers could use their wanted markup...
currently a use case can only be setup with
setup.addRole(role)
setup.addRole(role, constraint)
it must be also possible to do
setup.addRole(role, constraint1, constraint2, ..)
API and templates must provide this
Tech info table in output pdf is not sorted by title name
e.g.
Technical information - my use case
Technical information - my use case (group1)
Technical information - my use case (group2)
Remove brackets at copyright note at end of license file..
The freemarker templates currently doing many unnecessary empty lines on output.
One of top reasons (or maybe the only one) is that macro calls are always handled as a line - even when no output is done at all (e.g. on debug logging).
This should be improved - so output of xml is more pretty.
This is similar to #31 - but the allowed file format will be only html. It should prepare for other markups too.
Something like a Registry for file supports should be available
TextResourceRegistry.register(".html", new DocbookHTMLMarkupSupport());
So e.g. addTextResource("name.html") is allowed but not ("name.txt").
Currently a missing description does result in
but content elements have always a content where the content can be described more precise.
So when no description is set it does not matter
=> when no description is set
Currently <<ahref='...'>linktext supports only normal hyperlinks.
It would be very convenient to have something like
<a href='code2doc://package1.subpackage2.ConceptClass.class'>linktext
<a href='code2doc://package1.subpackage2.UseCaseClass.class'>linktext
<a href='code2doc://package1.subpackage2.ArchitectureClass.class'>linktext
<a href='code2doc://package1.subpackage2.RoleClass.class'>linktext
<a href='code2doc://package1.subpackage2.ConstraintClass.class'>linktext
Usecases contains a table (when defined) of possible roles.
The output must be ordered alphabetical
When adding example picture the output in PDF does not work 100%. Bigger pictures are not shown completeley.
Via Code2DocExtension projects should be able to support additional information.
E.g. "ExampleURLExtension" -> builds example urls automatically by project information.
e.g.
setup.addRole(role1,constraint1);
setup.addRole(role2)
--> should result in output:
role1 constraint1
rolw2 (no constraints)
Following roles are not allowed for this use case: role3, role4, role5, role6.
But this feature should be configurable (param.set("code2doc.usecase.show-unsupported-roles","true")
As an feature when no slash is given on a resource the same path as of element is automatically used
de.jcup.testpath.UseCase1.java with example resource "test.html" searches automatically inside
de/jcup/testpath/teset.html
It works for HTML but not for PNG
Wiki links should be shown on top of element in generated documentation .
e.g Section 2.1, “Create a concept” [6] used instead "create a concept"...
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.