From: Jean-Christophe Beaupré Date: Sat, 20 Dec 2014 23:52:59 +0000 (-0500) Subject: neo_doxygen: Add a class to manage brief descriptions. X-Git-Tag: v0.7~3^2~3 X-Git-Url: http://nitlanguage.org neo_doxygen: Add a class to manage brief descriptions. Signed-off-by: Jean-Christophe Beaupré --- diff --git a/contrib/neo_doxygen/src/doxml/doc_listener.nit b/contrib/neo_doxygen/src/doxml/doc_listener.nit index cf2490c..2b9df04 100644 --- a/contrib/neo_doxygen/src/doxml/doc_listener.nit +++ b/contrib/neo_doxygen/src/doxml/doc_listener.nit @@ -22,11 +22,11 @@ class DocListener super TextListener # The read documentation. - var doc = new JsonArray is writable + var doc = new Documentation is writable redef fun end_listening do super - var line = to_s.trim + var line = flush_buffer.trim if not line.is_empty then doc.add(line) end end diff --git a/contrib/neo_doxygen/src/model/descriptions.nit b/contrib/neo_doxygen/src/model/descriptions.nit new file mode 100644 index 0000000..1f504ef --- /dev/null +++ b/contrib/neo_doxygen/src/model/descriptions.nit @@ -0,0 +1,117 @@ +# This file is part of NIT ( http://www.nitlanguage.org ). +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Documentation associated to an entity. +module model::descriptions + +import json::static + +# Documentation associated to an entity. +# +# The documentation is written in Markdown format. +# +# ~~~nit +# var doc = new Documentation +# +# doc.brief_description = "Do something." +# doc.detailed_description = ["Do not lunch a rocket."] +# assert doc.brief_description == "Do something." +# assert doc.detailed_description == ["Do not lunch a rocket."] +# assert doc.to_json == """["Do something.","Do not lunch a rocket."]""" +# +# doc.brief_description = "" +# doc.detailed_description = ["The answer is `42`."] +# assert doc.brief_description == "The answer is `42`." +# assert doc.detailed_description == ["The answer is `42`."] +# assert doc.to_json == """["The answer is `42`."]""" +# +# doc.detailed_description = ["The answer is `42`."] +# doc.brief_description = "" +# assert doc.brief_description == "The answer is `42`." +# assert doc.detailed_description == ["The answer is `42`."] +# assert doc.to_json == """["The answer is `42`."]""" +# +# doc.detailed_description = new Array[String] +# doc.brief_description = "" +# assert doc.is_empty +# assert doc.brief_description == "" +# assert doc.detailed_description == new Array[String] +# assert doc.to_json == "[]" +# ~~~ +class Documentation + super Jsonable + + private var content = new JsonStringArray + private var has_brief_description: Bool = false + + # The brief description. + # + # If it is empty, the first element of `detailed_description` will be used + # as brief description. + fun brief_description=(brief_description: String) do + if brief_description.is_empty then + if has_brief_description then + content.shift + has_brief_description = false + end + else if has_brief_description then + content.first = brief_description + else + content.unshift(brief_description) + has_brief_description = true + end + end + + # The brief description. + fun brief_description: String do + if not is_empty then return content.first + return "" + end + + # The detailed description. + # + # Each element should represent a block. + fun detailed_description=(detailed_description: SequenceRead[String]) do + if has_brief_description then + while content.length > 1 do content.pop + else + content.clear + end + content.add_all(detailed_description) + end + + # The detailed description. + # + # Each element should represent a block. + fun detailed_description: SequenceRead[String] do + if not has_brief_description then return content + if content.length > 1 then return content.subarray(1, content.length - 1) + return new Array[String] + end + + # Add a block of detailed description. + fun add(block: String) do content.add block + + # Is the documentation empty? + fun is_empty: Bool do return content.is_empty + + redef fun to_json do return content.to_json + redef fun append_json(b) do content.append_json(b) +end + +# A `Jsonable` array of strings. +private class JsonStringArray + super JsonSequenceRead[String] + super Array[String] +end diff --git a/contrib/neo_doxygen/src/model/graph.nit b/contrib/neo_doxygen/src/model/graph.nit index 7c8d2a3..74a81b5 100644 --- a/contrib/neo_doxygen/src/model/graph.nit +++ b/contrib/neo_doxygen/src/model/graph.nit @@ -18,6 +18,7 @@ module model::graph import neo4j import more_collections import location +import descriptions # A Neo4j graph. class NeoGraph @@ -135,7 +136,7 @@ abstract class Entity var full_name: nullable String = null is writable # Associated documentation. - var doc = new JsonArray is writable + var doc = new Documentation is writable init do self.labels.add(graph.project_name) @@ -179,7 +180,7 @@ abstract class Entity # # Called by the loader when it has finished to read the entity. fun put_in_graph do - if doc.length > 0 then + if not doc.is_empty then set_mdoc end graph.all_nodes.add(self) diff --git a/contrib/neo_doxygen/src/tests/neo_doxygen_descriptions.nit b/contrib/neo_doxygen/src/tests/neo_doxygen_descriptions.nit new file mode 100644 index 0000000..d277be7 --- /dev/null +++ b/contrib/neo_doxygen/src/tests/neo_doxygen_descriptions.nit @@ -0,0 +1,44 @@ +# This file is part of NIT ( http://www.nitlanguage.org ). +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import model::descriptions + +# Copied from the documentation of `Documentation`. + +var doc = new Documentation + +doc.brief_description = "Do something." +doc.detailed_description = ["Do not lunch a rocket."] +assert doc.brief_description == "Do something." +assert doc.detailed_description == ["Do not lunch a rocket."] +assert doc.to_json == """["Do something.","Do not lunch a rocket."]""" + +doc.brief_description = "" +doc.detailed_description = ["The answer is `42`."] +assert doc.brief_description == "The answer is `42`." +assert doc.detailed_description == ["The answer is `42`."] +assert doc.to_json == """["The answer is `42`."]""" + +doc.detailed_description = ["The answer is `42`."] +doc.brief_description = "" +assert doc.brief_description == "The answer is `42`." +assert doc.detailed_description == ["The answer is `42`."] +assert doc.to_json == """["The answer is `42`."]""" + +doc.detailed_description = new Array[String] +doc.brief_description = "" +assert doc.is_empty +assert doc.brief_description == "" +assert doc.detailed_description == new Array[String] +assert doc.to_json == "[]" diff --git a/contrib/neo_doxygen/src/tests/neo_doxygen_doc_module_class.nit b/contrib/neo_doxygen/src/tests/neo_doxygen_doc_module_class.nit index 308e94a..48f73d5 100644 --- a/contrib/neo_doxygen/src/tests/neo_doxygen_doc_module_class.nit +++ b/contrib/neo_doxygen/src/tests/neo_doxygen_doc_module_class.nit @@ -23,18 +23,18 @@ var a_ns = new Namespace(graph) file.full_name = "Baz.java" file.declare_class("classa_bar", "a::Bar", "public") file.declare_namespace("namespacea", "a") -file.doc.add "A file." +file.doc.brief_description = "A file." file.put_in_graph a_ns.full_name = "a" a_ns.model_id = "namespacea" a_ns.declare_class("classa_bar", "a::Bar", "public") -a_ns.doc.add "A namespace." +a_ns.doc.brief_description = "A namespace." a_ns.put_in_graph bar_class.model_id = "classa_bar" bar_class.full_name = "a::Bar" -bar_class.doc.add "A class." +bar_class.doc.brief_description = "A class." bar_class.put_in_graph graph.add_global_modules diff --git a/contrib/neo_doxygen/src/tests/neo_doxygen_file_compound.nit b/contrib/neo_doxygen/src/tests/neo_doxygen_file_compound.nit index e1f59b2..c66709e 100644 --- a/contrib/neo_doxygen/src/tests/neo_doxygen_file_compound.nit +++ b/contrib/neo_doxygen/src/tests/neo_doxygen_file_compound.nit @@ -36,7 +36,7 @@ file.location = location file.declare_class("classa_b_bar", "a::b::Bar", "package") file.declare_class("classbaz", "Baz", "") file.declare_namespace("", "a::b") -file.doc.add "The first file." +file.doc.brief_description = "The first file." file.put_in_graph file_2.name = "Bar.java" diff --git a/contrib/neo_doxygen/src/tests/neo_doxygen_namespace_members.nit b/contrib/neo_doxygen/src/tests/neo_doxygen_namespace_members.nit index 4e67bfe..4030df9 100644 --- a/contrib/neo_doxygen/src/tests/neo_doxygen_namespace_members.nit +++ b/contrib/neo_doxygen/src/tests/neo_doxygen_namespace_members.nit @@ -33,7 +33,7 @@ member.put_in_graph ns.model_id = "namespacefoo" ns.name = "foo" ns.declare_member(member) -ns.doc.add "A documented namespace." +ns.doc.brief_description = "A documented namespace." ns.put_in_graph root_ns.declare_namespace("namespacefoo", "") diff --git a/tests/nitg-g.skip b/tests/nitg-g.skip index e24a345..0d0961d 100644 --- a/tests/nitg-g.skip +++ b/tests/nitg-g.skip @@ -1,6 +1,7 @@ nitc nitdoc nitlight +neo_doxygen_descriptions neo_doxygen_doc_module_class neo_doxygen_dump neo_doxygen_file_compound diff --git a/tests/sav/neo_doxygen_descriptions.res b/tests/sav/neo_doxygen_descriptions.res new file mode 100644 index 0000000..e69de29